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Introduction 


Advanced MS-DOS Programming is written for the experienced C or 
assembly-language programmer. It provides all the information you need 
to write robust, high-performance applications under the MS-DOS operat- 
ing system. Because I believe that working, well-documented programs 
are unbeatable learning tools, I have included detailed programming 
examples throughout— including complete utility programs that you can 
adapt to your own needs. 


This book is both a tutorial and a reference and is divided into four 
sections, so that you can find information more easily. Section I discusses 
MS-DOS capabilities and services by functional group in the context of 
common programming issues, such as user input, control of the display, 
memory management, and file handling. Special classes of programs, 
such as interrupt handlers, device drivers, and filters, have their own 
chapters. 


Section II provides a complete reference guide to MS-DOS function calls, 
organized so that you can see the calling sequence, results, and version 
dependencies of each function at a glance. I have also included notes, 
where relevant, about quirks and special uses of functions as well as 
cross-references to related functions. An assembly-language example is 
included for each entry in Section II. 


Sections III and IV are references to IBM ROM BIOS, Microsoft Mouse 
driver, and Lotus/Intel/Microsoft Expanded Memory Specification func- 
tions. The entries in these two sections have the same form as in Section 
II, except that individual programming examples have been omitted. 


The programs in this book were written with the marvelous Brief editor 
from Solution Systems and assembled or compiled with Microsoft Macro 
Assembler version 5.1 and Microsoft C Compiler version 5.1. They have 
been tested under MS-DOS versions 2.1, 3.1, 3.3, and 4.0 on an 8088-based 
IBM PC, an 80286-based IBM PC/AT, and an 80386-based IBM PS/2 Model 
80. As far as am aware, they do not contain any software or hardware de- 
pendencies that will prevent them from running properly on any IBM PC— 
compatible machine running MS-DOS version 2.0 or later. 


Xiil 


Changes from the First Edition 


Xiv 


Readers who are familiar with the first edition will find many changes in 
the second edition, but the general structure of the book remains the 
same. Most of the material comparing MS-DOS to CP/M and UNIX/XENIX 
has been removed; although these comparisons were helpful a few years 
ago, MS-DOS has become its own universe and deserves to be considered 
On its own terms. 


The previously monolithic chapter on character devices has been broken 
into three more manageable chapters focusing on the keyboard and 
mouse, the display, and the serial port and printer. Hardware-dependent 
video techniques have been de-emphasized; although this topic is more 
important than ever, it has grown so complex that it requires a book of its 
own. A new chapter discusses compatibility and portability of MS-DOS 
applications and also contains a brief introduction to Microsoft OS/ 2, the 
new multitasking, protected-mode operating system. 


A road map to vital figures and tables has been added, following the Table 
of Contents, to help you quickly locate the layouts of the program segment 
prefix, file control block, and the like. 


The reference sections at the back of the book have been extensively up- 
dated and enlarged and are now complete through MS-DOS version 4.0, 
the IBM PS/2 Model 80 ROM BIOS and the VGA video adapter, the 
Microsoft Mouse driver version 6.0, and the Lotus/Intel/Microsoft Ex- 
panded Memory Specification version 4.0. 


In the two years since Advanced MS-DOS Programming was first 
published, hundreds of readers have been kind enough to send me their 
comments, and I have tried to incorporate many of their suggestions in 
this new edition. As before, please feel free to contact me via MCI Mail 
(user name LMI), CompuServe (user ID 72406,1577), or BIX (user name 
rduncan). 


Ray Duncan 


Los Angeles, California 
September 1988 


SPECIAL OFFER 


Companion Disk to 
ADVANCED MS-DOS PROGRAMMING, 
2nd edition 


Microsoft Press has created a Companion Disk to ADVANCED Ms- 
DOS PROGRAMMING, 2nd edition, available in either 5.25-inch or 
3.5-inch format. This disk contains all of the source files and execut- 
able files from the book and is an essential resource for anyone who 
wants to forgo the drudgery of typing code (and the time required to 
find and correct those inevitable typing errors). 


The Companion Disk to ADVANCED MS-DOS PROGRAMMING is 
available only from Microsoft Press. To order, use the special reply 
card bound in the back of the book. If the card has already been used, 
send $19.95, plus sales tax if applicable (CA residents 5% plus.local op- 
tion tax, CT 7.5%, FL 6%, MA 5%, MN 6%, MO 4.225%, NY 4% plus lo- 
cal option tax, WA State 7.8%) and $2.50 per disk for domestic postage 
-and handling, $6.00 per disk for foreign orders to: Microsoft Press, 
Attn: Companion Disk Offer, 21919 20th Ave S.E., Box 3011, Bothell, 
WA 98041-3011. Please specify 5.25-inch or 3.5-inch format. Payment 
must be in U.S. funds. You may pay by check or money order (payable 
to Microsoft Press) or by American Express, VISA, or MasterCard; 
please include both your credit card number and the expiration date. 
All orders are shipped 2nd day air upon receipt of order to Microsoft. 


If you have questions or comments about this disk, please contact Ray 
Duncan via MCI Mail (user name LMI), CompuServe (user ID 
72406,1577), or BIX (user name rduncan). 


If this disk proves defective, please send the defective disk along with 
your packing slip to: Microsoft Press, Consumer Sales, 16011 NE 36th 
Way, Box 97017, Redmond, WA 98073-9717. 
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Chapter 1 


In only seven years, MS-DOS has evolved from a simple program loader 
into a sophisticated, stable operating system for personal computers that 
are based on the Intel 8086 family of microprocessors (Figure 1-1). MS- 
DOS supports networking, graphical user interfaces, and storage devices 
of every description; it serves as the platform for thousands of application 
programs; and it has over 10 million licensed users—dwarfing the com- 
bined user bases of all of its competitors. 


The progenitor of MS-DOS was an operating system called 86-DOS, which 
was written by Tim Paterson for Seattle Computer Products in mid-1980. 
At that time, Digital Research’s CP/M-80 was the operating system most 
commonly used on microcomputers based on the Intel 8080 and Zilog 
Z-80 microprocessors, and a wide range of application software (word 
processors, database managers, and so forth) was available for use with 
CP/M-80. | 


To ease the process of porting 8-bit CP/M-80 applications into the new 16- 
bit environment, 86-DOS was originally designed to mimic CP/M-80 in 
both available functions and style of operation. Consequently, the struc- 
tures of 86-DOS’s file control blocks, program segment prefixes, and exe- 
cutable files were nearly identical to those of CP/M-80. Existing CP/M-80 
programs could be converted mechanically (by processing their source- 
code files through a special translator program) and, after conversion, 
would run under 86-DOS either immediately or with very little hand 
editing. 


Because 86-DOS was marketed as a proprietary Operating system for 
Seattle Computer Products’ line of S-100 bus, 8086-based microcomputers, 
it made very little impact on the microcomputer world in general. Other 
vendors of 8086-based microcomputers were understandably reluctant to 
adopt a competitor's operating system and continued to wait impatiently 
for the release of Digital Research’s CP/M-86. 


In October’ 1980, IBM approached the major microcomputer-software 
houses in search of an operating system for the new line of personal com- 
puters it was designing. Microsoft had no operating system of its own to 
offer (other than a stand-alone version of Microsoft BASIC) but paid a fee 
to Seattle Computer Products for the right to sell Paterson’s 86-DOS. (At 
that time, Seattle Computer Products received a license to use and sell 
Microsoft's languages and all 8086 versions of Microsoft’s operating sys- 
tem.) In July 1981, Microsoft purchased all rights to 86-DOS, made sub- 
stantial alterations to it, and renamed it MS-DOS. When the first IBM PC 
was released in the fall of 1981, IBM offered MS-DOS (referred to as PC- 
DOS 1.0) as its primary operating system. 
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IBM also selected Digital Research’s CP/M-86 and Softech’s P-system as 
alternative operating systems for the PC. However, they were both very 
slow to appear at IBM PC dealers and suffered the additional disadvan- 
tages of higher prices and lack of available programming languages. IBM 
threw its considerable weight behind PC-DOS by releasing all the IBM- 
logo PC application software and development tools to run under it. Con- 
sequently, most third-party software developers targeted their products 
for PC-DOS from the start, and CP/M-86 and P-system never became sig- 
nificant factors in the IBM PC—compatible market. 


In spite of some superficial similarities to its ancestor CP/M-80, MS-DOS 
version 1.0 contained a number of improvements over CP/M-80, including 
the following: 


= Animproved disk-directory structure that included information about 
a file’s attributes (such as whether it was a system or a hidden file), its 
exact size in bytes, and the date that the file was created or last 
modified 


= A superior disk-space allocation and management method, allowing 
extremely fast sequential or random record access and program 
loading 


= An expanded set of operating-system services, including hardware- 
independent function calls to set or read the date and time, a filename 
parser, multiple-block record I/O, and variable record sizes 


= An AUTOEXEC.BAT batch file to perform a user-defined series of 
commands when the system was started or reset 


IBM was the only major computer manufacturer (sometimes referred to as 
OEM, for original equipment manufacturer) to ship MS-DOS version 1.0 
(as PC-DOS 1.0) with its products. MS-DOS version 1.25 (equivalent to IBM 
PC-DOS 1.1) was released in June 1982 to fix a number of bugs and also to 
support double-sided disks and improved hardware independence in the 
DOS kernel. This version was shipped by several vendors besides IBM, in- 
cluding Texas Instruments, COMPAQ, and Columbia, who all entered the 
personal computer market early. Due to rapid decreases in the prices of 
RAM and fixed disks, MS-DOS version 1 is no longer in common use. 


MS-DOS version 2.0 (equivalent to PC-DOS 2.0) was first released in March 
1983. It was, in retrospect, a new operating system (though great care was 
taken to maintain compatibility with MS-DOS version 1). It contained 
many significant innovations and enhanced features, including those 
listed on the following page. 
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Support for both larger-capacity floppy disks and hard disks 


Many UNIX/XENIX-like features, including a hierarchical file struc- 
ture, file handles, I/O redirection, pipes, and filters 


Background printing (print spooling) 
Volume labels, plus additional file attributes 
a Installable device drivers 


a A user-customizable system-configuration file that controlled the load- 
ing of additional device drivers, the number of system disk buffers, and 
so forth 


Maintenance of environment blocks that could be used to pass infor- 
mation between programs 


a An optional ANSI display driver that allowed programs to position the 
cursor and control display characteristics in a hardware-independent 
manner 


Support for the dynamic allocation, modification, and release of 
memory by application programs 


a Support for customized user command interpreters (shells) 


System tables to assist application software in modifying its currency, 
time, and date formats (known as international support) 


MS-DOS version 2.11 was subsequently released to improve international 
support (table-driven currency symbols, date formats, decimal-point sym- 
bols, currency separators, and so forth), to add support for 16-bit Kanji 
characters throughout, and to fix a few minor bugs. Version 2.11 rapidly 
became the base version shipped for 8086/8088-based personal com- 
puters by every major OEM, including Hewlett-Packard, Wang, Digital 
Equipment Corporation, Texas Instruments, COMPAQ, and Tandy. 


MS-DOS version 2.25, released in October 1985, was distributed in the Far 
East but was never shipped by OEMs in the United States and Europe. In 
this version, the international support for Japanese and Korean character 
sets was extended even further, additional bugs were repaired, and many 
of the system utilities were made compatible with MS-DOS version 3.0. 


MS-DOS version 3.0 was introduced by IBM in August 1984 with the 
release of the 80286-based PC/AT machines. It represented another major 
rewrite of the entire operating system and included the important new 
features listed on the following page. 
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Direct control of the print spooler by application software 
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Further expansion of international support for currency formats 


® Extended error reporting, including a code that suggests a recovery 
strategy to the application program 


Support for file and record locking and sharing 
@ Support for larger fixed disks 


MS-DOS version 3.1, which was released in November 1984, added sup- 
port for the sharing of files and printers across a network. Beginning with 
version 3.1, a new operating-system module called the redirector inter- 
cepts an application program’s requests for I/O and filters out the requests 
that are directed to network devices, passing these requests to another 
machine for processing. 


Since version 3.1, the changes to MS-DOS have been evolutionary rather 
than revolutionary. Version 3.2, which appeared in 1986, generalized the 
definition of device drivers so that new media types (such as 3.5-inch 
floppy disks) could be supported more easily. Version 3.3 was released in 
1987, concurrently with the new IBM line of PS/2 personal computers, and 
drastically expanded MS-DOS’s multilanguage support for keyboard map- 
pings, printer character sets, and display fonts. Version 4.0, delivered in 
1988, was enhanced with a visual shell as well as support for very large file 
systems. 


While MS-DOS has been evolving, Microsoft has also put intense efforts 
into the areas of user interfaces and multitasking operating systems. 
Microsoft Windows, first shipped in 1985, provides a multitasking, graphi- 
cal user “desktop” for MS-DOS systems. Windows has won widespread 
support among developers of complex graphics applications such as 
desktop publishing and computer-aided design because it allows their 
programs to take full advantage of whatever output devices are available 
without introducing any hardware dependence. 


Microsoft Operating System/2 (MS OS/2), released in 1987, represents a 
new standard for application developers: a protected-mode, multitasking, 
virtual-memory system specifically designed for applications requiring 
high-performance graphics, networking, and interprocess communica- 
tions. Although MS OS/2 is a new product and is not a derivative of 
MS-DOS, its user interface and file system are compatible with MS-DOS 
and Microsoft Windows, and it offers the ability to run one real-mode (MS- 
DOS) application alongside MS OS/2 protected-mode applications. This 
compatibility allows users to move between the MS-DOS and OS/2 envi- 
ronments with a minimum of difficulty. 
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MS-DOS 1.0 

PC-DOS 1.0 1981: First operating system on IBM PC 

| MS-DOS 1.25 | Double-sided disk support and bug fixes added: 
a ~=PC-DOS 1.1 widely distributed by OEMs other than IBM 
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Figure 1-1. The evolution of MS-DOS. 
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What does the future hold for MS-DOS? Only the long-range planning 
teams at Microsoft and IBM know for sure. But it seems safe to assume that 
MS-DOS, with its relatively small memory requirements, adaptability to 
diverse hardware configurations, and enormous base of users, will remain 
important to programmers and software publishers for years to come. 


Genealogy of MS-DOS 


Chapter 2 


in Operation 


It is unlikely that you will ever be called upon to configure the MS-DOS 
software for a new model of computer. Still, an acquaintance with the 
general structure of MS-DOS can often be very helpful in understanding 
the behavior of the system as a whole. In this chapter, we will discuss how 
MS-DOS is organized and how it is loaded into memory when the com- 
puter is turned on. 


The Structure of MS-DOS 


MS-DOS is partitioned into several layers that serve to isolate the kernel 
logic of the operating system, and the user’s perception of the system, 
from the hardware it is running on. These layers are 


a The BIOS (Basic Input/Output System) 
= The DOS kernel 
s The command processor (shell) 


We'll discuss the functions of each of these layers separately. 


The BIOS Module 
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The BIOS is specific to the individual computer system and is provided by 
the manufacturer of the system. It contains the default resident hardware- 
dependent drivers for the following devices: 


a Console display and keyboard (CON) 
= Line printer (PRN) 

m Auxiliary device (AUX) 

a Date and time (CLOCK$) 

= Boot disk device (block device) 


The MS-DOS kernel communicates with these device drivers through I/O 
request packets; the drivers then translate these requests into the proper 
commands for the various hardware controllers. In many MS-DOS sys- 
tems, including the IBM PC, the most primitive parts of the hardware 
drivers are located in read-only memory (ROM) so that they can be used 
by stand-alone applications, diagnostics, and the system startup program. 


The terms resident and installable are used to distinguish between the 
drivers built into the BIOS and the drivers installed during system initial- 
ization by DEVICE commands in the CONFIG.SYS file. (installable drivers 
will be discussed in more detail later in this chapter and in Chapter 14.) 
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The BIOS is read into random-access memory (RAM) during system ini- 
tialization as part of a file named IO.SYS. (In PC-DOS, the file is called 
IBMBIO.COM.) This file is marked with the special attributes hidden and 
system. 


The DOS Kernel 


The DOS kernel implements MS-DOS as it is seen by application pro- 
grams. The kernel is a proprietary program supplied by Microsoft Corpo- 
ration and provides a collection of hardware-independent services called 
system functions. These functions include the following: 


File and record management 

= Memory management 

= Character-device input/output 
= Spawning of other programs 

= Access to the real-time clock 


Programs can access system functions by loading registers with function- 
specific parameters and then transferring to the operating system by 
means of a software interrupt. 


The DOS kernel is read into memory during system initialization from the 
MSDOS.SYS file on the boot disk. (The file is called IBMDOS.COM in PC- 
DOS.) This file is marked with the attributes hidden and system. 


The Command Processor 


The command processor, or shell, is the user’s interface to the operating 
system. It is responsible for parsing and carrying out user commands, in- 
cluding the loading and execution of other programs from a disk or other 
mass-storage device. 


The default shell that is provided with MS-DOS is found in a file called 
COMMAND.COM. Although COMMAND.COM prompts and responses 
constitute the ordinary user’s complete perception of MS-DOS, it is im- 
portant to realize that COMMAND.COM is not the operating system, but 
simply a special class of program running under the control of MS-DOS. 


COMMAND.COM can be replaced with a shell of the programmer’s own 
design by simply adding a SHELL directive to the system-configuration 
file (CONFIG.SYS) on the system startup disk. The product COMMAND- 
PLUS from ESP Systems is an example of such an alternative shell. 
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More about COMMAND.COM 
The default MS-DOS shell, COMMAND.COM, is divided into three parts: 


a Aresident portion 
a An initialization section 
x A transient module 


The resident portion is loaded in lower memory, above the DOS kernel 
and its buffers and tables. It contains the routines to process Ctrl-C and 
Ctrl-Break, critical errors, and the termination (final exit) of other tran- 
sient programs. This part of COMMAND.COM issues error messages and 
is responsible for the familiar prompt 


Abort, Retry, Ignore? 


The resident portion also contains the code required to reload the tran- 
sient portion of COMMAND.COM when necessary. 


The initialization section of COMMAND.COM is loaded above the resi- 
dent portion when the system is started. It processes the AUTOEXEC.BAT 
batch file (the user’s list of commands to execute at system startup), if one 
is present, and is then discarded. 


The transient portion of COMMAND.COM is loaded at the high end of 
memory, and its memory can also be used for other purposes by applica- 
tion programs. The transient module issues the user prompt, reads the 
commands from the keyboard or batch file, and causes them to be exe- 
cuted. When an application program terminates, the resident portion of 
COMMAND.COM does a checksum of the transient module to determine 
whether it has been destroyed and fetches a fresh copy from the disk if 
necessary. 


The user commands that are accepted by COMMAND.COM fall into three 
categories: 


Internal commands 
a External commands 
«# Batch files 


Internal commands, sometimes called intrinsic commands, are those 
carried out by code embedded in COMMAND.COM itself. Commands in 
this category include COPY, REN(AME), DIRCECTORY), and DEL(ETE). 
The routines for the internal commands are included in the transient part 
of COMMAND.COM. 
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External commands, sometimes called extrinsic commands or transient 
programs, are the names of programs stored in disk files. Before these 
programs can be executed, they must be loaded from the disk into the 
transient program area (TPA) of memory. (See “How MS-DOS Is Loaded” 
in this chapter.) Familiar examples of external commands are CHKDSK, 
BACKUP, and RESTORE. As soon as an external command has completed 
its work, it is discarded from memory; hence, it must be reloaded from 
disk each time it is invoked. 


Batch files are text files that contain lists of other intrinsic, extrinsic, or 
batch commands. These files are processed by a special interpreter that is 
built into the transient portion of COMMAND.COM. The interpreter reads 
the batch file one line at a time and carries out each of the specified 
operations in order. 


In order to interpret a user’s command, COMMAND.COM first looks to 
see if the user typed the name of a built-in Gntrinsic) command that it can 
carry out directly. If not, it searches for an external command (executable 
program file) or batch file by the same name. The search is carried out 
- first in the current directory of the current disk drive and then in each of 
the directories specified in the most recent PATH command. In each 
directory inspected, COMMAND.COM first tries to find a file with the ex- 
tension .COM, then .EXE, and finally .BAT. If the search fails for all three 
file types in all of the possible locations, COMMAND.COM displays the 
familiar message 


Bad command or file name 


If a .COM file or a .EXE file is found, COMMAND.COM uses the MS-DOS 
EXEC function to load and execute it. The EXEC function builds a special 
data structure called a program segment prefix (PSP) above the resident 
portion of COMMAND.COM in the transient program area. The PSP con- 
tains various linkages and pointers needed by the application program. 
Next, the EXEC function loads the program itself, just above the PSP, and 
performs any relocation that may be necessary. Finally, it sets up the 
registers appropriately and transfers control to the entry point for the pro- 
gram. (Both the PSP and the EXEC function will be discussed in more 
detail in Chapters 3 and 12.) When the transient program has finished its 
job, it calls a special MS-DOS termination function that releases the tran- 
sient program’s memory and returns control to the program that caused 
the transient program to be loaded (COMMAND.COM, in this case). 


A transient program has nearly complete control of the system’s resources 
while it is executing. The only other tasks that are accomplished are those 
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performed by interrupt handlers (such as the keyboard input driver and 
the real-time clock) and operations that the transient program requests 
from the operating system. MS-DOS does not support sharing of the 
central processor among several tasks executing concurrently, nor can it 
wrest control away from a program when it crashes or executes for too 
long. Such capabilities are the province of MS OS/2, which is a protected- 
mode system with preemptive multitasking (time-slicing). 
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When the system is started or reset, program execution begins at address 
OFFFFOH. This is a feature of the 8086/8088 family of microprocessors 
and has nothing to do with MS-DOS. Systems based on these processors 
are designed so that address OFFFFOH lies within an area of ROM and con- 
tains a jump machine instruction to transfer control to system test code 
and the ROM bootstrap routine (Figure 2-1). 


The ROM bootstrap routine reads the disk bootstrap routine from the first 
sector of the system startup disk (the boot sector) into memory at some 
arbitrary address and then transfers control to it (Figure 2-2). (The boot 
sector also contains a table of information about the disk format.) 


The disk bootstrap routine checks to see if the disk contains a copy of MS- 
DOS. It does this by reading the first sector of the root directory and 
determining whether the first two files are IO.SYS and MSDOS.SYS (or 
IBMBIO.COM and IBMDOS.COM), in that order. If these files are not pres- 
ent, the user is prompted to change disks and strike any key to try again. 


ROM bootstrap routine 
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Figure 2-1. A typical 8086/8088-based computer system immediately after system 
startup or reset. Execution begins at location OFFFFOH, which contains a jump in- 
struction that directs program control to the ROM bootstrap routine. 
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Figure 2-2. The ROM bootstrap routine loads the disk bootstrap routine into memory 
from the first sector of the system startup disk and then transfers control to it. 


If the two system files are found, the disk bootstrap reads them into 
memory and transfers control to the initial entry point of IO.SYS (Figure 
2-3). (In some implementations, the disk bootstrap reads only IO.SYS into 
memory, and IO.SYS in turn loads the MSDOS.SYS file.) 


The IO.SYS file that is loaded from the disk actually consists of two sepa- 
rate modules. The first is the BIOS, which contains the linked set of resi- 
dent device drivers for the console, auxiliary port, printer, block, and 
clock devices, plus some hardware-specific initialization code that is run 
only at system startup. The second module, SYSINIT, is supplied by 
Microsoft and linked into the IO.SYS file, along with the BIOS, by the 
computer manufacturer. 


SYSINIT is called by the manufacturer’s BIOS initialization code. It deter- 
mines the amount of contiguous memory present in the system and then 
relocates itself to high memory. Then it moves the DOS kernel, 
MSDOS.SYS, from its original load location to its final memory location, 
overlaying the original SYSINIT code and any other expendable initializa- 
tion code that was contained in the IO.SYS file (Figure 2-4). 


Next, SYSINIT calls the initialization code in MSDOS.SYS. The DOS 
kernel initializes its internal tables and work areas, sets up the interrupt 
vectors 20H through 2FH, and traces through the linked list of resident de- 
vice drivers, calling the initialization function for each. (See Chapter 14.) 
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Figure 2-3. The disk bootstrap reads the file IO.SYS into memory. This file contains 
the MS-DOS BIOS (resident device drivers) and the SYSINIT module. Either the disk 
bootstrap or the BIOS (depending upon the manufacturer’s implementation) then 
reads the DOS kernel into memory from the MSDOS.SYS file. 


These driver functions determine the equipment status, perform any nec- 
essary hardware initialization, and set up the vectors for any external 
hardware interrupts the drivers will service. 


As part of the initialization sequence, the DOS kernel examines the disk- 
parameter blocks returned by the resident block-device drivers, deter- 
mines the largest sector size that will be used in the system, builds some 
drive-parameter blocks, and allocates a disk sector buffer. Control then 
returns to SYSINIT. 


When the DOS kernel has been initialized and all resident device drivers 
are available, SYSINIT can call on the normal MS-DOS file services to 
open the CONFIG.SYS file. This optional file can contain a variety of com- 
mands that enable the user to customize the MS-DOS environment. For 
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Figure 2-4. SYSINIT moves itself to high memory and relocates the DOS kernel, 
MSDOS.SYS, downward to its final address. The MS-DOS disk buffer cache and file 
control block areas are allocated, and then the installable device drivers specified in 
the CONFIG.SYS file are loaded and linked into the system. 


instance, the user can specify additional hardware device drivers, the 
number of disk buffers, the maximum number of files that can be open at 
one time, and the filename of the command processor (shell). 


If it is found, the entire CONFIG.SYS file is loaded into memory for pro- 
cessing. All lowercase characters are converted to uppercase, and the file 
is interpreted one line at a time to process the commands. Memory is allo- 
cated for the disk buffer cache and the internal file control blocks used by 
the handle file and record system functions. (See Chapter 8.) Any device 
drivers indicated in the CONFIG.SYS file are sequentially loaded into 
memory, initialized by calls to their init modules, and linked into the 
device-driver list. The init function of each driver tells SYSINIT how 
much memory to reserve for that driver. 


After all installable device drivers have been loaded, SYSINIT closes all 
file handles and reopens the console (CON), printer (PRN), and auxiliary 
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(AUX) devices as the standard input, standard output, standard error, stan- 
dard list, and standard auxiliary devices. This allows a user-installed 
character-device driver to override the BIOS’s resident drivers for the 
standard devices. 


Finally, SYSINIT calls the MS-DOS EXEC function to load the command 
interpreter, or shell. (The default shell is COMMAND.COM, but another 
shell can be substituted by means of the CONFIG.SYS file.) Once the shell 
is loaded, it displays a prompt and waits for the user to enter a command. 
MS-DOS is now ready for business, and the SYSINIT module is discarded 
(Figure 2-5). 
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Figure 2-5. The final result of the MS-DOS startup process for a typical system. The 
resident portion of COMMAND.COM lies in low memory, above the DOS kernel. The 
transient portion containing the batch-file interpreter and intrinsic commands is 
placed in high memory, where it can be overlaid by extrinsic commands and appli- 
cation programs running in the transient program area. 
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Chapter 3 


Structure of MS-DOS 
Application Programs 


Programs that run under MS-DOS come in two basic flavors: .COM pro- 
grams, which have a maximum size of approximately 64 KB, and .EXE 
programs, which can be as large as available memory. In Intel 8086 
parlance, .COM programs fit the tiny model, in which all segment regis- 
ters contain the same value; that is, the code and data are mixed together. 
In contrast, .EXE programs fit the small, medium, or large model, in which 
the segment registers contain different values; that is, the code, data, and 
stack reside in separate segments. .EXE programs can have multiple code 
and data segments, which are respectively addressed by long calls and by 
manipulation of the data segment (DS) register. 


A .COM-type program resides on the disk as an absolute memory image, 
in a file with the extension .COM. The file does not have a header or any 
other internal identifying information. A .EXE program, on the other 
hand, resides on the disk in a special type of file with a unique header, a 
relocation map, a checksum, and other information that is (or can be) 
used by MS-DOS. 


Both .COM and .EXE programs are brought into memory for execution by 
the same mechanism: the EXEC function, which constitutes the MS-DOS 
loader. EXEC can be called with the filename of a program to be loaded by 
COMMAND.COM (the normal MS-DOS command interpreter), by other 
shells or user interfaces, or by another program that was previously loaded 
by EXEC. If there is sufficient free memory in the transient program area, 
EXEC allocates a block of memory to hold the new program, builds the 
program segment prefix (PSP) at its base, and then reads the program into 
memory immediately above the PSP. Finally, EXEC sets up the segment 
registers and the stack and transfers control to the program. 


When it is invoked, EXEC can be given the addresses of additional infor- 
mation, such as a command tail, file control blocks, and an environment 
block; if supplied, this information will be passed on to the new program. 
(The exact procedure for using the EXEC function in your own programs 
is discussed, with examples, in Chapter 12.) 


-COM and .EXE programs are often referred to as transient programs. A 
transient program “owns” the memory block it has been allocated and has 
nearly total control of the system’s resources while it is executing. When 
the program terminates, either because it is aborted by the operating sys- 
tem or because it has completed its work and systematically performed a 
final exit back to MS-DOS, the memory block is then freed (hence the 
term transient) and can be used by the next program in line to be loaded. 
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The Program Segment Prefix 


A thorough understanding of the program segment prefix is vital to suc- 
cessful programming under MS-DOS. It is a reserved area, 256 bytes long, 
that is set up by MS-DOS at the base of the memory block allocated to a 
transient program. The PSP contains some linkages to MS-DOS that can be 
used by the transient program, some information MS-DOS saves for its 
own purposes, and some information MS-DOS passes to the transient 
program—to be used or not, as the program requires (Figure 3-1). 
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Figure 3-1. The structure of the program segment prefix. 


Structure of MS-DOS Application Programs 23 


In the first versions of MS-DOS, the PSP was designed to be compatible 
with a control area that was built beneath transient programs under Digi- 
tal Research’s venerable CP/M operating system, so that programs could 
be ported to MS-DOS without extensive logical changes. Although MS- 
DOS has evolved considerably since those early days, the structure of the 
PSP is still recognizably similar to its CP/M equivalent. For example, offset 
Q000H in the PSP contains a linkage to the MS-DOS process-termination 
handler, which cleans up after the program has finished its job and per- 
forms a final exit. Similarly, offset 0005H in the PSP contains a linkage to 
the MS-DOS function dispatcher, which performs disk operations, con- 
sole input/output, and other such services at the request of the transient 
program. Thus, calls to PSP:0000 and PSP:0005 have the same effect as 
CALL 0000 and CALL 0005 under CP/M. (These linkages are not the 
“approved” means of obtaining these services, however.) 


The word at offset 0002H in the PSP contains the segment address of the 
top of the transient program’s allocated memory block. The program can 
use this value to determine whether it should request more memory to do 
its job or whether it has extra memory that it can release for use by other 
processes. 


Offsets OOOAH through 0015H in the PSP contain the previous contents of 
the interrupt vectors for the termination, Ctrl-C, and critical-error han- 
dlers. If the transient program alters these vectors for its own purposes, 
MS-DOS restores the original values saved in the PSP when the program 
terminates. 


The word at PSP offset 002CH holds the segment address of the environ- 
ment block, which contains a series of ASCIIZ strings (sequences of ASCII 
characters terminated by a null, or zero, byte). The environment block is 
inherited from the program that called the EXEC function to load the cur- 
rently executing program. It contains such information as the current 
search path used by COMMAND.COM to find executable programs, the 
location on the disk of COMMAND.COM itself, and the format of the user 
prompt used by COMMAND.COM. 


The command tail—the remainder of the command line that invoked the 
transient program, after the program’s name—is copied into the PSP 
starting at offset 0081H. The length of the command tail, not including the 
return character at its end, is placed in the byte at offset 0080H. Redi- 
rection or piping parameters and their associated filenames do not appear 
in the portion of the command line (the command tail) that is passed to 
the transient program, because redirection is transparent to applications. 
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To provide compatibility with CP/M, MS-DOS parses the first two parame- 
ters in the command tail into two default file control blocks (FCBs) at 
PSP:005CH and PSP:006CH, under the assumption that they may be file- 
names. However, if the parameters are filenames that include a path speci- 
fication, only the drive code will be valid in these default FCBs, because 
FCB-type file- and record-access functions do not support hierarchical file 
structures. Although the default FCBs were an aid in earlier years, when 
compatibility with CP/M was more of a concern, they are essentially use- 
less in modern MS-DOS application programs that must provide full path 
support. (File control blocks are discussed in detail in Chapter 8 and 
hierarchical file structures are discussed in Chapter 9.) 


The 128-byte area from 0080H through OOFFH in the PSP also serves as 
the default disk transfer area (DTA), which is set by MS-DOS before pass- 
ing control to the transient program. If the program does not explicitly 
change the DTA, any file read or write operations requested with the FCB 
group of function calls automatically use this area as a data buffer. This is 
rarely useful and is another facet of MS-DOS’s handling of the PSP that is 
present only for compatibility with CP/M. 


OQ WARNING Programs must not alter any part of the PSP below 
offset OO5CH. 


Introduction to .COM Programs 


Programs of the .COM persuasion are stored in disk files that hold an ab- 
solute image of the machine instructions to be executed. Because the files 
contain no relocation information, they are more compact, and are loaded 
for execution slightly faster, than equivalent .EXE files. Note that MS-DOS 
does not attempt to ascertain whether a .COM file actually contains exe- 
cutable code (there is no signature or checksum, as in the case of a .EXE 
file); it simply brings any file with the .COM extension into memory and 
jumps to it. 


Because .COM programs are loaded immediately above the program seg- 
ment prefix and do not have a header that can specify another entry point, 
they must always have an origin of 0100H, which is the length of the PSP. 
Location 0100H must contain an executable instruction. The maximum 
length of a .COM program is 65,536 bytes, minus the length of the PSP 
(256 bytes) and a mandatory word of stack (2 bytes). 


When control is transferred to the .COM program from MS-DOS, all of the 
segment registers point to the PSP (Figure 3-2). The stack pointer (SP) 
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Figure 3-2. A memory image of a typical .COM-type program after loading. The 
contents of the .COM file are brought into memory just above the program segment 
prefix. Program, code, and data are mixed together in the same segment, and all seg- 
ment registers contain the same value. 


register contains OFFFEH if memory allows; otherwise, it is set as high as 
possible in memory minus 2 bytes. (MS-DOS pushes a zero word on the 
stack before entry.) 


Although the size of an executable .COM file can’t exceed 64 KB, the cur- 
rent versions of MS-DOS allocate all of the transient program area to .COM 
programs when they are loaded. Because many such programs date from 
the early days of MS-DOS and are not necessarily “well-behaved” in their 
approach to memory management, the operating system simply makes 
the worst-case assumption and gives .COM programs everything that is 
available. If a .COM program wants to use the EXEC function to invoke 
another process, it must first shrink down its memory allocation to the 
minimum memory it needs in order to continue, taking care to protect its 
stack. (This is discussed in more detail in Chapter 12.) 


When a .COM program finishes executing, it can return control to MS- 
DOS by several means. The preferred method is Int 21H Function 4CH, 
which allows the program to pass a return code back to the program, 
shell, or batch file that invoked it. However, if the program is running 
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under MS-DOS version 1, it must exit by means of Int 20H, Int 21H Func- 
tion 0, or a NEAR RETURN. (Because a word of zero was pushed onto the 
stack at entry, a NEAR RETURN causes a transfer to PSP:0000, which con- 
tains an Int 20H instruction.) 


A .COM-type application can be linked together from many separate ob- 
ject modules. All of the modules must use the same code-segment name 
and class name, and the module with the entry point at offset 0100H 
within the segment must be linked first. In addition, all of the procedures 
within a .COM program should have the NEAR attribute, because all exe- 
cutable code resides in one segment. 


When linking a .COM program, the linker will display the message 
Warning: no stack segment 


This message can be ignored. The linker output is a EXE file, which must 
be converted into a .COM file with the MS-DOS EXE2BIN utility before 
execution. You can then delete the .EXE file. (An example of this process 
is provided in Chapter 4.) 


An Example .COM Program 


The HELLO.COM program listed in Figure 3-3 demonstrates the structure 
of a simple assembly-language program that is destined to become a 
COM file. CYou may find it helpful to compare this listing with the 
HELLO.EXE program later in this chapter.) Because this program is SO 
short and simple, a relatively high proportion of the source code is ac- 
tually assembler directives that do not result in any executable code. 


The NAME statement simply provides a module name for use during the 
linkage process. This aids understanding of the map that the linker pro- 
duces. In MASM versions 5.0 and later, the module name is always the 
same as the filename, and the NAME statement is ignored. 


The PAGE command, when used with two operands, as in line 2, defines 
the length and width of the page. These default respectively to 66 lines 
and 80 characters. If you use the PAGE command without any operands, a 
formfeed is sent to the printer and a heading is printed. In larger pro- 
grams, use the PAGE command liberally to place each of your subroutines 
on separate pages for easy reading. 


The TITLE command, in line 3, specifies the text string (limited to 60 
characters) that is to be printed at the upper left corner of each page. The 
TITLE command is optional and cannot be used more than once in each 
assembly-language source file. 
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Figure 3-3. The HELLO.COM program listing. 
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Figure 3-3. continued 


defines entry point = 


Dropping down past a few comments and EQU statements, we come to a 
declaration of a code segment that begins in line 22 with a SEGMENT 
command and ends in line 49 with an ENDS command. The label in the 
leftmost field of line 22 gives the code segment the name _TEXT. The 
operand fields at the right end of the line give the segment the attributes 
WORD, PUBLIC, and ‘CODE’. (You might find it helpful to read the 
Microsoft Macro Assembler manual for detailed explanations of each pos- 
sible segment attribute.) 


Because this program is going to be converted into a .COM file, all of its 
executable code and data areas must lie within one code segment. The 
program must also have its origin at offset 0100H (immediately above the 
program segment prefix), which is taken care of by the ORG statement 
in line 24. 


Following the ORG instruction, we encounter an ASSUME statement on 
line 27. The concept of ASSUME often baffles new assembly-language 
programmers. In a way, ASSUME doesn’t “do” anything; it simply tells the 
assembler which segment registers you are going to use to point to the 
various segments of your program, so that the assembler can provide seg- 
ment overrides when they are necessary. It’s important to notice that the 
ASSUME statement doesn’t take care of loading the segment registers with 
the proper values; it merely notifies the assembler of your intent to do that 
within the program. (Remember that, in the case of a .COM program, MS- 
DOS initializes all the segment registers before entry to point to the PSP.) 


Within the code segment, we come to another type of block declaration 
that begins with the PROC command on line 29 and closes with ENDP on 
line 40. These two instructions declare the beginning and end of a pro- 
cedure, a block of executable code that performs a single distinct func- 
tion. The label in the leftmost field of the PROC statement Cin this case, 
print) gives the procedure a name. The operand field gives it an attribute. 
If the procedure carries the NEAR attribute, only other code in the same 
segment can call it, whereas if it carries the FAR attribute, code located 
anywhere in the CPU’s memory-addressing space can call it. In .COM 
programs, all procedures carry the NEAR attribute. 
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For the purposes of this example program, I have kept the print pro- 
cedure ridiculously simple. It calls MS-DOS Int 21H Function 40H to send 
the message Hello World! to the video screen, and calls Int 21H Function 
4CH to terminate the program. 


The END statement in line 51 tells the assembler that it has reached the 
end of the source file and also specifies the entry point for the program. If 
the entry point is not a label located at offset 0100H, the .EXE file resulting 
from the assembly and linkage of this source program cannot be con- 
verted into a .COM file. 


Introduction to .EXE Programs 


30 


We have just discussed a program that was written in such a way that it 
could be assembled into a .COM file. Such a program is simple in struc- 
ture, SO a programmer who needs to put together this kind of quick utility 
can concentrate on the program logic and do a minimum amount of wor- 
rying about control of the assembler. However, .COM-type programs have 
some definite disadvantages, and so most serious assembly-language 
efforts for MS-DOS are written to be converted into .EXE files. 


Although .COM programs are effectively restricted to a total size of 64 KB 
for machine code, data, and stack combined, .EXE programs can be prac- 
tically unlimited in size (up to the limit of the computer’s available 
memory). .EXE programs also place the code, data, and stack in separate 
parts of the file. Although the normal MS-DOS program loader does not 
take advantage of this feature of .EXE files, the ability to load different 
parts of large programs into several separate memory fragments, as well 
as the opportunity to designate a “pure” code portion of your program 
that can be shared by several tasks, is very significant in multitasking envi- 
ronments such as Microsoft Windows. 


The MS-DOS loader always brings a .EXE program into memory immedi- 
ately above the program segment prefix, although the order of the code, 
data, and stack segments may vary (Figure 3-4). The .EXE file has a 
header, or block of control information, with a characteristic format 
(Figures 3-5 and 3-6). The size of this header varies according to the num- 
ber of program instructions that need to be relocated at load time, but it is 
always a multiple of 512 bytes. 


Before MS-DOS transfers control to the program, the initial values of the 
code segment (CS) register and instruction pointer (IP) register are calcu- 
lated from the entry-point information in the .EXE file header and the 
program's load address. This information derives from an END statement 
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Figure 3-4. A memory image of 4 typical .EXE-type program immediately after 
loading. The contents of the .EXE file are relocated and brought into memory above 
the program segment prefix. Code, data, and stack reside in separate segments and 
need not be in the order shown here. The entry point can be anywhere in the code seg- 
ment and is specified by the END statement in the main module of the program. When 
the program receives control, the DS (data segment) and ES (extra segment) registers 
point to the program segment prefix; the program usually saves this value and then 
resets the DS and ES registers to point to its data area. 


in the source code for one of the program’s modules. The data segment 
(DS) and extra segment (ES) registers are made to point to the PSP so that 
the program can access the environment-block pointer, command tail, 
and other useful information contained there. 


The initial contents of the stack segment (SS) and stack pointer (SP) regis- 
ters come from the header. This information derives from the declaration 
of a segment with the attribute STACK somewhere in the program's 
source code. The memory space allocated for the stack may be initialized 
or uninitialized, depending on the stack-segment definition, many pro- 
grammers like to initialize the stack memory with a recognizable data pat- 
tern so that they can inspect memory dumps and determine how much 
stack space is actually used by the program. 


When a .EXE program finishes processing, it should return control to MS- 
DOS through Int 21H Function 4CH. Other methods are available, but they 
offer no advantages and are considerably less convenient (because they 
usually require the CS register to point to the PSP). 
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Byte offset 
0000H 
0001H 


0002H 


0004H 
0006H 
0008H 
OOOAH 
000CH 
OOOEH 
0010H 
0012H 
0014H 
0016H 
0018H 
001AH 
001BH 


. First part of .EXE file signature (4DH) 

: Second part of .EXE file signature (SAH) 
Length of file MOD 512 

: Size of file in 512-byte pages, including header 


Number of relocation-table items 
Size of header in paragraphs (16-byte units) 
Minimum number of paragraphs needed above program 
Maximum number of paragraphs desired above program 
Segment displacement of stack module 
Contents of SP register at entry 


Poe ones eee 


Se 


Contents of IP register at entry 
Segment displacement of code module 
Offset of first relocation item in file 
Overlay number (0 for resident part of program) 
Variable reserved space 


BS SENSU SRT RES 


BRANSON REL eA Baa herbie se aay PND ERNE Cre DOSE OONCN SS et Ss Dany a ORR ROSIN sevacnonanesh nie ptes 
Bcc BSN ee OR 1OD SOA AEROS ARUN SCTE NERS SEROO : 


ve 


Seen YE CNS 


Relocation table 


Variable reserved space 


: 
oe 
He 
4 
S 
| 
a 
aS 
a 


Program and data segments 


Stack segment 


ce 
RENEE RR ee RIS SS ESRD CES LUZERN came ance 


Figure 3-5. The format of a EXE load module. 


The input to the linker for a -EXE-type program can be many separate ob- 
ject modules. Each module can use a unique code-segment name, and the 
procedures can carry either the NEAR or the FAR attribute, depending on 
naming conventions and the size of the executable code. The program- 
mer must take care that the modules linked together contain only one seg- 
ment with the STACK attribute and only one entry point defined with an 
END assembler directive. The output from the linker is a file with a .EXE 


extension. This file can be executed immediately. 
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Figure 3-6. A hex dump of the HELLO.EXE program, demonstrating the contents of 
a simple .EXE load module. Note the following interesting values: the EXE signature 
in bytes OOOOH and 0001H, the number of relocation-table items in bytes OOOGH and 
0007H, the minimum extra memory allocation (MIN_ALLOC) in bytes OOOAH and 
OOOBH, the maximum extra memory allocation (MAX_ALLOC) in bytes OOOCH 

and OOODH, and the initial IP (instruction pointer) register value in bytes OO14H and 
0015H. See also Figure 3-5. 


An Example .EXE Program 


The HELLO.EXE program in Figure 3-7 demonstrates the fundamental 
structure of an assembly-language program that is destined to become a 
EXE file. At minimum, it should have a module name, a code segment, a 
stack segment, and a primary procedure that receives control of the com- 
puter from MS-DOS after the program is loaded. The HELLO.EXE pro- 
gram also contains a data segment to provide a more complete example. 


The NAME, TITLE, and PAGE directives were covered in the HELLO.COM 
example program and are used in the same manner here, so we'll move to 
the first new item of interest. After a few comments and EQU statements, 
we come to a declaration of a code segment that begins on line 21 with a 
SEGMENT command and ends on line 41 with an ENDS command. As in 
the HELLO.COM example program, the label in the leftmost field of the 
line gives the code segment the name _TEXT. The operand fields at the 
right end of the line give the attributes WORD, PUBLIC, and ‘CODE’. 


Following the code-segment instruction, we find an ASSUME statement on 
line 23. Notice that, unlike the equivalent statement in the HELLO.COM 
program, the ASSUME statement in this program specifies several differ- 
ent segment names. Again, remember that this statement has no direct 
effect on the contents of the segment registers but affects only the opera- 
tion of the assembler itself. 
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Oo ON DO LSP WD Ff 
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° 
id 
° 
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name 
page 
_ title 


HELLO. EXE: 


Ray Duncan, May y 1988 


stdin equ 
Stdout equ 
stderr equ 


cr equ 


1 


f equ 


assume 


print proc 


mov 
mov 


mov 
mov 
mov 
mov 
int 


mov 
int 


print  endp 


TEXT ends 


_DATA segment 


msg db 


db 


TEXT segment y 


ax,DATA. ma 


2th 


hello 
95,132 


jagiiege. program, MEE bee Seohentd 
and an MS. ‘DOS. ‘function 


cs:_TEXT,ds:_DATA,ss:STACK 


far a at ; enti 


ds,ax- oe * : 


ah,40h =. Funct 
bx, stdout ob stan 

CX még tens —-s Teng 
dx, offset msg: a ires 
21h BOP ; transfer 


ax, 4c00h ees 


Mort ON 


cr,1f ae message to display, ‘ 
‘Hello World!" ,cr, Tt. ee 


Figure 3-7. The HELLO.EXE program listing. (continued) 
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Figure 3-7. continued 


Within the code segment, the main print procedure is declared by the 
PROC command on line 25 and closed with ENDP on line 39. Because the 
procedure resides in a .EXE file, we have given it the FAR attribute as an 
example, but the attribute is really irrelevant because the program is so 
small and the procedure is not called by anything else in the same 
program. 


The print procedure first initializes the DS register, as indicated in the 
earlier ASSUME statement, loading it with a value that causes it to point to 
the base of the data area. (MS-DOS automatically sets up the CS and SS 
registers.) Next, the procedure uses MS-DOS Int 21H Function 40H to dis- 
play the message Hello World! on the screen, just as in the HELLO.COM 
program. Finally, the procedure exits back to MS-DOS with an Int 21H 
Function 4CH on lines 36 and 37, passing a return code of zero (which by 
convention means a success). 


Lines 44 through 51 declare a data segment named _DATA, which con- 
tains the variables and constants the program will use. If the various mod- 
ules of a program contain multiple data segments with the same name, the 
linker will collect them and place them in the same physical memory 
segment. 


Lines 54 through 58 establish a stack segment; PUSH and POP instructions 
will access this area of scratch memory. Before MS-DOS transfers control 
to a .EXE program, it sets up the SS and SP registers according to the 
declared size and location of the stack segment. Be sure to allow enough 
room for the maximum stack depth that can occur at runtime, plus a safe 
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number of extra words for registers pushed onto the stack during an MS- 
DOS service call. If the stack overflows, it may damage your other code 
and data segments and cause your program to behave strangely or even to 
crash altogether! 


The END statement on line 60 winds up our brief HELLO.EXE program, 
telling the assembler that it has reached the end of the source file and pro- 
viding the label of the program’s point of entry from MS-DOS. 


The differences between .COM and .EXE programs are summarized in 
Figure 3-8. 


Neen Ses 


-COM program EXE program 
Maximum size 65,536 bytes minus 256 bytes No limit 
for PSP and 2 bytes for stack 
Entry point PSP:0100H Defined by END statement 
AL at entry OOH if default FCB #1 has valid § Same 
drive, OFFH if invalid drive 
AH at entry 00H if default FCB #2 has valid Same 
drive, OFFH if invalid drive 
CS at entry PSP Segment containing module 
with entry point 
IP at entry 0100H Offset of entry point within 
its segment 
DS at entry PSP PSP 
ES at entry PSP PSP 
SS at entry PSP Segment with STACK 
attribute 
SP at entry OFFFEH or top word in avail- Size of segment defined with 
able memory, whichever is STACK attribute 
lower 
Stack at entry Zero word Initialized or uninitialized 
Stack size 65,536 bytes minus 256 bytes Defined in segment with 
for PSP and size of execut- STACK attribute 
able code and data 
Subroutine calls Usually NEAR NEAR or FAR 
Exit method Int 21H Function 4CH Int 21H Function 4CH 
preferred, NEAR RET if preferred 
MS-DOS version 1 
Size of file Exact size of program Size of program plus header 


(multiple of 512 bytes) 


Figure 3-8. Summary of the differences between .COM and .EXE programs, includ- 
ing their entry conditions. 
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More About Assembly-Language Programs 


Now that we’ve looked at working examples of .COM and .EXE assembly- 
language programs, let’s backtrack and discuss their elements a little more 
formally. The following discussion is based on the Microsoft Macro As- 
sembler, hereafter referred to as MASM. If you are familiar with MASM 
and are an experienced assembly-language programmer, you may want to 
skip this section. 


MASM programs can be thought of as having three structural levels: 
= The module level 

s The segment level 

= The procedure level 


Modules are simply chunks of source code that can be independently 
maintained and assembled. Segments are physical groupings of like items 
(machine code or data) within a program and a corresponding segrega- 
tion of dissimilar items. Procedures are functional subdivisions of an exe- 
cutable program—routines that carry out a particular task. 


Program Modules 


Under MS-DOS, the module-level structure consists of files containing the 
source code for individual routines. Each source file is translated by the as- 
sembler into a relocatable object module. An object module can reside 
alone in an individual file or with many other object modules in an object- 
module library of frequently used or related routines. The Microsoft Ob- 
ject Linker (LINK) combines object-module files, often with additional 
object modules extracted from libraries, into an executable program file. 


Using modules and object-module libraries reduces the size of your appli- 
cation source files (and vastly increases your productivity), because these 
files need not contain the source code for routines they have in common 
with other programs. This technique also allows you to maintain the rou- 
tines more easily, because you need to alter only one copy of their source 
code stored in one place, instead of many copies stored in different appli- 
cations. When you improve (or fix) one of these routines, you can simply 
reassemble it, put its object module back into the library, relink all of the 
programs that use the routine, and voila: instant upgrade. 
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The term segmenis refers to two discrete programming concepts: physical 
segments and logical segments. 


Physical segments are 64 KB blocks of memory. The Intel 8086/8088 and 
80286 microprocessors have four segment registers, which are essentially 
used as pointers to these blocks. (The 80386 has six segment registers, 
which are a superset of those found on the 8086/8088 and 80286.) Each 
segment register can point to the bottom of a different 64 KB area of 
memory. Thus, a program can address any location in memory by appro- 
priate manipulation of the segment registers, but the maximum amount of 
memory that it can address simultaneously is 256 KB. 


As we discussed earlier in the chapter, .COM programs assume that all 
four segment registers always point to the same place—the bottom of the 
program. Thus, they are limited to a maximum size of 64 KB. .EXE pro- 
grams, on the other hand, can address many different physical segments 
and can reset the segment registers to point to each segment as it is 
needed. Consequently, the only practical limit on the size of a EXE pro- 
gram is the amount of available memory. The example programs through- 
out the remainder of this book focus on .EXE programs. 


Logical segments are the program components. A minimum of three logi- 
cal segments must be declared in any EXE program: a code segment, a 
data segment, and a stack segment. Programs with more than 64 KB of 
code or data have more than one code or data segment. The routines or 
data that are used most frequently are put into the primary code and data 
segments for speed, and routines or data that are used less frequently are 
put into secondary code and data segments. 


Segments are declared with the SEGMENT and ENDS directives in the 
following form: 


name SEGMENT attributes 


name ENDS 


The attributes of a segment include its align type (BYTE, WORD, or 
PARA), combine type (PUBLIC, PRIVATE, COMMON, or STACK), and 
class type. The segment attributes are used by the linker when it is com- 
bining logical segments to create the physical segments of an executable 
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program. Most of the time, you can get by just fine using a small selection 
of attributes in a rather stereotypical way. However, if you want to use the 
full range of attributes, you might want to read the detailed explanation in 
the MASM manual. 


Programs are classified into one memory model or another based on the 
number of their code and data segments. The most commonly used 
memory model for assembly-language programs is the small model, 
which has one code and one data segment, but you can also use the 
medium, compact, and large models (Figure 3-9). (Two additional models 
exist with which we will not be concerning ourselves further: the tiny 
model, which consists of intermixed code and data in a single segment— 
for example, a .COM file under MS-DOS; and the huge model, which is 
supported by the Microsoft C Optimizing Compiler and which allows use 
of data structures larger than 64 KB.) 


fe a I 


Model Code segments Data segments 
Small One One 

Medium Multiple One 

Compact One Multiple 

Large Multiple Multiple 


Figure 3-9. Memory models commonly used in assembly-language and C programs. 


For each memory model, Microsoft has established certain segment and 
class names that are used by all its high-level-language compilers (Figure 
3-10). Because segment names are arbitrary, you may as well adopt the 
Microsoft conventions. Their use will make it easier for you to integrate 
your assembly-language routines into programs written in languages such 
as C, or to use routines from high-level-language libraries in your 
assembly-language programs. 


Another important Microsoft high-level-language convention is to use the 
GROUP directive to name the near data segment (the segment the pro- 
gram expects to address with offsets from the DS register) and the stack 
segment as members of DGROUP (the automatic data group), a special 
name recognized by the linker and also by the program loaders in 
Microsoft Windows and Microsoft OS/2. The GROUP directive causes log- 
ical segments with different names to be combined into a single physical 
segment so that they can be addressed using the same segment base ad- 
dress. In C programs, DGROUP also contains the local heap, which is 
used by the C runtime library for dynamic allocation of small amounts 
of memory. 
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Cane 


Memory Align Combine Class 
model Segment name type type type Group 
Small _TEXT WORD PUBLIC CODE 
DATA WORD PUBLIC DATA DGROUP 
STACK PARA STACK STACK DGROUP 
Medium module_TEXT WORD PUBLIC CODE 
DATA WORD PUBLIC DATA DGROUP 
STACK PARA STACK STACK DGROUP 
Compact —TEXT WORD PUBLIC CODE 
data PARA PRIVATE FAR_DATA 
~DATA WORD PUBLIC DATA DGROUP 
STACK PARA STACK STACK DGROUP 
Large module_TEXT WORD PUBLIC CODE 
data PARA PRIVATE FAR_DATA 
—DATA WORD PUBLIC DATA DGROUP 
STACK PARA STACK STACK DGROUP 


Figure 3-10. Segments, groups, and classes for the standard memory models as used 
with assembly-language programs. The Microsoft C Optimizing Compiler and other 
high-level-language compilers use a superset of these segments and classes. 


For pure assembly-language programs that will run under MS-DOS, you 
can ignore DGROUP. However, if you plan to integrate assembly-language 
routines and programs written in high-level languages, you'll want to fol- 
low the Microsoft DGROUP convention. For example, if you are planning 
to link routines from a C library into an assembly-language program, you 
should include the line 


DGROUP group _DATA,STACK 


near the beginning of the program. 


The final Microsoft convention of interest in creating EXE programs is 
segment order. The high-level compilers assume that code segments al- 
ways come first, followed by far data segments, followed by the near data 
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segment, with the stack and heap last. This order won’t concern you much 
until you begin integrating assembly-language code with routines from 
high-level-language libraries, but it is easiest to learn to use the conven- 
tion right from the start. 


Program Procedures 


The procedure level of program structure is partly real and partly concep- 
tual. Procedures are basically just a fancy guise for subroutines. 


Procedures within a program are declared with the PROC and ENDP 
directives in the following form: 


name PROC attribute 


RET 
name ENDP 


The attribute carried by a PROC declaration, which is either NEAR or FAR, 
tells the assembler what type of call you expect to use to enter the pro- 
cedure—that is, whether the procedure will be called from other routines 
in the same segment or from routines in other segments. When the assem- 
bler encounters a RET instruction within the procedure, it uses the 
attribute information to generate the correct opcode for either a near 
(intra-segment) or far (inter-segment) return. 


Each program should have a main procedure that receives control from 
MS-DOS. You specify the entry point for the program by including the 
name of the main procedure in the END statement in one of the pro- 
gram’s source files. The main procedure’s attribute (NEAR or FAR) is 
really not too important, because the program returns control to MS-DOS 
with a function call rather than a RET instruction. However, by conven- 
tion, most programmers assign the main procedure the FAR attribute 
any way. 


You should break the remainder of the program into procedures in an or- 
derly way, with each procedure performing a well-defined single func- 
tion, returning its results to its caller, and avoiding actions that have global 
effects within the program. Ideally procedures invoke each other only by 
CALL instructions, have only one entry point and one exit point, and al- 
ways exit by means of a RET instruction, never by jumping to some other 
location within the program. 
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For ease of understanding and maintenance, a procedure should not ex- 
ceed one page (about 60 lines); if it is longer than a page, it is probably too 
complex and you should delegate some of its function to one or more sub- 
sidiary procedures. You should preface the source code for each pro- 
cedure with a detailed comment that states the procedure’s calling 
sequence, results returned, registers affected, and any data items accessed 
or modified. The effort invested in making your procedures compact, 
clean, flexible, and well-documented will be repaid many times over 
when you reuse the procedures in other programs. 
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Chapter 4 


MS-DOS Programming Tools 


Preparing a new program to run under MS-DOS is an iterative process 
with four basic steps: 


= Use of a text editor to create or modify an ASCII source-code file 


= Use of an assembler or high-level-language compiler (such as the 
Microsoft Macro Assembler or the Microsoft C Optimizing Compiler) to 
translate the source file into relocatable object code 


a Use of a linker to transform the relocatable object code into an execut- 
able MS-DOS load module 


= Use of a debugger to methodically test and debug the program 


Additional utilities the MS-DOS software developer may find necessary or 
helpful include the following: 


a LIB, which creates and maintains object-module libraries 
u CREF, which generates a cross-reference listing 
= EXEZ2BIN, which converts .EXE files to .COM files 


a MAKE, which compares dates of files and carries out operations based 
on the result of the comparison 


This chapter gives an operational overview of the Microsoft program- 
ming tools for MS-DOS, including the assembler, the C compiler, the 
linker, and the librarian. In general, the information provided here also 
applies to the IBM programming tools for MS-DOS, which are really the 
Microsoft products with minor variations and different version numbers. 
Even if your preferred programming language is not C or assembly lan- 
guage, you will need at least a passing familiarity with these tools because 
all of the examples in the IBM and Microsoft DOS reference manuals are 
written in one of these languages. 


The survey in this chapter, together with the example programs and refer- 
ence section elsewhere in the book, should provide the experienced pro- 
grammer with sufficient information to immediately begin writing useful 
programs. Readers who do not have a background in C, assembly lan- 
guage, or the Intel 80x86 microprocessor architecture should refer to the 
tutorial and reference works listed at the end of this chapter. 
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File Types 


The MS-DOS programming tools can create and process many different 
file types. The following extensions are used by convention for these files: 


Extension 


ANC 


.LIB 


.LST 


MAP 


OBJ 
(REF 


File type 


Assembly-language source file 

C source file 

MS-DOS executable load module that does not require relocation at 
runtime 

Cross-reference information file produced by the assembler for 
processing by CREF.EXE 

Module-definition file describing a program’s segment behavior 
(MS OS/2 and Microsoft Windows programs only; not relevant 
to normal MS-DOS applications) 

MS-DOS executable load module that requires relocation at 
runtime 

C header file containing C source code for constants, macros, and 
functions, merged into another C program with the #include 
directive 

Include file for assembly-language programs, typically containing 
macros and/or equates for systemwide values such as error 
codes 

Object-module library file made up of one or more .OBJ files; 
indexed and manipulated by LIB.EXE 

Program listing, produced by the assembler, that includes memory 
locations, machine code, the original program text, and error 
messages 

Listing of symbols and their locations within a load module; 
produced by the linker 

Relocatable-object-code file produced by an assembler or compiler 

Cross-reference listing produced by CREF.EXE from the 
information in a .CRF file 


The Microsoft Macro Assembler 


The Microsoft Macro Assembler (MASM) is distributed as the file 
MASM.EXE. When beginning a program translation, MASM needs the fol- 
lowing information: 


® The name of the file containing the source program 


® The filename for the object program to be created 


® The destination of the program listing 


= The filename for the information that is later processed by the cross- 
reference utility (CREF EXE) 
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You can invoke MASM in two ways. If you enter the name of the assembler 
alone, it prompts you for the names of each of the various input and output 
files. The assembler supplies reasonable defaults for all the responses ex- 
cept the source filename, as shown in the following example: 


C>MASM <Enter> 


Microsoft (R) Macro Assembler Version 5.10 
Copyright (C) Microsoft Corp 1981, 1988. All rights reserved. 


Source filename [.ASM]: HELLO <Enter> 
Object filename [(HELLO.OBJJ: <Enter> 
Source listing [NUL.LST]: <Enter> 
Cross-reference [NUL.CRF]: <Enter> 


49006 Bytes symbol space free 


0 Warning Errors 
0 Severe Errors 


C> 


You can use a logical device name (such as PRN or COM1) at any of the 
MASM prompts to send that output of the assembler to a character device 
rather than a file. Note that the default for the listing and cross-reference 
files is the NUL device —that is, no file is created. If you end any response 
with a semicolon, MASM assumes that the remaining responses are all to 
be the default. 


A more efficient way to use MASM is to supply all parameters in the com- 
mand line, as follows: 


MASM [options] source,[object],{listing],{crossref] 


For example, the following command lines are equivalent to the preceding 
interactive session: 


C>MASM HELLO,,NUL,NUL <Enter> 
or 
C>MASM HELLO; <Enter> 


These commands use the file HEZLO.ASM as the source, generate the 
object-code file HELLO.OB/J, and send the listing and cross-reference files 
to the bit bucket. 
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MASM accepts several optional switches in the command line, to control 
code generation and output files. Figure 4-1 lists the switches accepted by 
MASM version 5.1. As shown in the following example, you can put fre- 
quently used options in a MASM environment variable, where they will be 
found automatically by the assembler: 


C>SET MASM=/T /Zi <Enter> 
The switches in the environment variable will be overridden by any that 


you enter in the command line. 


In other versions of the Microsoft Macro Assembler, additional or fewer 
switches may be available. For exact instructions, see the manual for the 
version of MASM that you are using. 


Switch Meaning 


/A Arrange segments in alphabetic order. 

/Bn Set size of source-file buffer Gin KB). 

/C Force creation of a cross-reference (.CRF) file. 

/D Produce listing on both passes (to find phase errors). 


/Dsymbol Define symbol as a null text string (symbol can be referenced by 
conditional assembly directives in file). 


/E Assemble for 80x87 numeric coprocessor emulator using IEEE real- 
number format. 

Npath Set search path for include files. 

/L Force creation of a program-listing file. 

/LA Force listing of all generated code. 

/ML Preserve case sensitivity in all names (uppercase names distinct from 
their lowercase equivalents). 

/MX Preserve lowercase in external names only (names defined with PUBLIC 
or EXTRN directives). 

/MU Convert all lowercase names to uppercase. 

/N Suppress generation of tables of macros, structures, records, segments, 
groups, and symbols at the end of the listing. 

/P Check for impure code in 80286/80386 protected mode. 

/S Arrange segments in order of occurrence (default). 

rast “Terse” mode; suppress all messages unless errors are encountered 
during the assembly. 

/V “Verbose” mode; report number of lines and symbols at end of assembly. 

[Wn Set error display (warning) level; n=0-2. 

/X Force listing of false conditionals. 

/Z, Display source lines containing errors on the screen. 

/Zd Include line-number information in .OBJ file. 

/Zi Include line-number and symbol information in .OBJ file. 


Figure 4-1. Microsoft Macro Assembler version 5.1 switches. 
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MASM allows you to override the default extensions on any file—a feature 
that can be rather dangerous. For example, if in the preceding example 
you had responded to the Object filename prompt with HELLO. ASM, the 
assembler would have accepted the entry without comment and destroyed 
your source file. This is not too likely to happen in the interactive com- 
mand mode, but you must be very careful with file extensions when 
MASM is used in a batch file. 


The Microsoft C Optimizing Compiler 


The Microsoft C Optimizing Compiler consists of three executable files— 
C1.EXE, C2.EXE, and C3.EXE—that implement the C preprocessor, lan- 
guage translator, code generator, and code optimizer. An additional con- 
trol program, CL.EXE, executes the three compiler files in order, passing 
each the necessary information about filenames and compilation options. 


Before using the C compiler and the linker, you need to set up four envi- 
ronment variables: 


Variable Action 


PATH=path Specifies the location of the three executable C compiler files (C1, 
C2, and C3) if they are not in the current directory; used by 
CL.EXE. 

INCLUDE=path Specifies the location of #include files (default extension .H) that 
are not found in the current directory. 


LIB=path Specifies the location(s) for object-code libraries that are not found 
in the current directory. 

TMP=path Specifies the location for temporary working files created by the C 
compiler and linker. 


CL.EXE does not support an interactive mode or response files. You al- 
ways invoke it with a command line of the following form: 


CL [options] file [file ...] 


You may list any number of files—if a file has a .C extension, it will be 
compiled into a relocatable-object-module (.OBJ) file. Ordinarily, if the 
compiler encounters no errors, it automatically passes all resulting .OBJ 
files and any additional .OBJ files specified in the command line to the 
linker, along with the names of the appropriate runtime libraries. 


The C compiler has many optional switches controlling its memory 
models, output files, code generation, and code optimization. These are 
summarized in Figure 4-2. The C compiler’s arcane switch syntax is 
derived largely from UNIX/XENIKX, so don’t expect it to make any sense. 
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Switch 
/AX 


/C 


/D<name>|=text] 


/E 

/EP 

/F<n> 

/Fa [filename] 
/Fc [filename] 
/Fe [ filename] 
/F\ [filename] 
/Fm | filename] 
/Fo [filename] 
/FPX 


/Fs [filename] 
/Gx 


/H<n> 
/\<path> 

/J 

/link [options] 
/Ox 


Figure 4-2. Microsoft C Optimizing Compiler version 5.1 switches. 


Meaning 


Select memory model: 
C = compact model 
H = huge model 
L = large model 
M = medium model 
S = small model (default) 
Compile only; do not invoke linker. 
Do not strip comments. 
Define macro. 
Send preprocessor output to standard output. 
Send preprocessor output to standard output without line numbers. 
Set stack size (in hexadecimal bytes). 
Generate assembly listing. 
Generate mixed source/object listing. 
Force executable filename. 
Generate object listing. 
Generate map file. 
Force object-module filename. 
Select floating-point control: 
a = calls with alternate math library 
c = calls with emulator library 
c87 = calls with 8087 library 
i= in-line with emulator (default) 
i87 = in-line with 8087 
Generate source listing. 
Select code generation: 
0 = 8086 instructions (default) 
1 = 186 instructions 
2 = 286 instructions 
c = Pascal style function calls 
s = no stack checking 
t{[n] = data size threshold 
Specify external name length. 
Specify additional #include path. 
Specify default char type as unsigned. 
Pass switches and library names to linker. 
Select optimization: 
a = ignore aliasing 
d = disable optimizations 
i= enable intrinsic functions 
| = enable loop optimizations 
n = disable “unsafe” optimizations 
p = enable precision optimizations 
r = disable in-line return 
S = optimize for space 


(continued) 
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The Microsoft Object Lin! 


Figure 4-2. continued 
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Switch Meaning 
/Ox t = optimize for speed (default) 
(continued) w = ignore aliasing except across function calls 
x = enable maximum optimization (equivalent to /Oailt /Gs) 
/P Send preprocessor output to file. 
/SXx Select source-listing control: 


l<columns> = set line width 
p<lines> = set page length 
s<string> = set subtitle string 
t<string> = set title string 


/Te<file> Compile file without .C extension. 

/u Remove all predefined macros. 
/U<name> Remove specified predefined macro. 
/V<string> Set version string. 

/W<n> Set warning level (0-3). 

/X Ignore “standard places” for include files. 
/ZX Select miscellaneous compilation control: 


a = disable extensions 

c = make Pascal functions case-insensitive 

d = include line-number information 

e = enable extensions (default) 

g = generate declarations 

i = include symbolic debugging information 
1 = remove default library info 

p<mn> = pack structures on n-byte boundary 
s = check syntax only 


ker 


The object module produced by MASM from a source file is in a form that 
contains relocation information and may also contain unresolved refer- 
ences to external locations or subroutines. It is written in a common for- 
mat that is also produced by the various high-level compilers (such as 
FORTRAN and C) that run under MS-DOS. The computer cannot execute 
object modules without further processing. 


The Microsoft Object Linker (LINK), distributed as the file LINK.EXE, ac- 
cepts one or more of these object modules, resolves external references, 
includes any necessary routines from designated libraries, performs any 
necessary Offset relocations, and writes a file that can be loaded and exe- 
cuted by MS-DOS. The output of LINK is always in .EXE load-module for- 
mat. (See Chapter 3.) 
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As with MASM, you can give LINK its parameters interactively or by enter- 
ing all the required information in a single command line. If you enter the 
name of the linker alone, the following type of dialog ensues: 


C>LINK <Enter> 


Microsoft (R) Overlay Linker Version 3.61 
Copyright (C) Microsoft Corp 1983-1987. All rights reserved. 


Object Modules [.0BJ]: HELLO <Enter> 
Run File [HELLO.EXE]: <Enter> 

List File [NUL.MAP]: HELLO <Enter> 
Libraries [.LIBJ: <Enter> 


C> 


If you are using LINK version 4.0 or later, the linker also asks for the name 
of a module-definition (.DEF) file. Simply press the Enter key in response 
to such a prompt. Module-definition files are used when building 
Microsoft Windows or MS OS/2 “new .EXE” executable files but are not 
relevant in normal MS-DOS applications. 


The input file for this example was HELLO.OBJ; the output files were 
HELLO.EXE (the executable program) and HELLO.MAP (the load map 
produced by the linker after all references and addresses were resolved). 
Figure 4-3 shows the load map. 


Figure 4-3. Map produced by the Microsoft Object Linker (LINK) during the genera- 
tion of the HELLO.EXE program from Chapter 3. The program contains one CODE, 
one DATA, and one STACK segment. The first instruction to be executed lies in the 

first byte of the CODE segment. The $$TYPES and $$SYMBOLS segments contain in- 

formation for the CodeView debugger and are not part of the program; these segments 
are ignored by the normal MS-DOS loader. 
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You can obtain the same result more quickly by entering all parameters in 
the command line, in the following form: 


LINK options objectfile, exefile], (mapfile), [libraries] 

Thus, the command-line equivalent to the preceding interactive session is 
C>LINK HELLO,HELLO,HELLO,, <Enter> 

or 

C>LINK HELLO,,HELLO; <Enter> 


If you enter a semicolon as the last character in the command line, LINK 
assumes the default values for all further parameters. 


A third method of commanding LINK is with a response file. A response 
file contains lines of text that correspond to the responses you would give 
the linker interactively. You specify the name of the response file in the 
command line with a leading @ character, as follows: 


LINK @/filename 


You can also enter the name of a response file at any prompt. If the response 
file is not complete, LINK will prompt you for the missing information. 


When entering linker commands, you can specify multiple object files 
with the + operator or with spaces, as in the following example: 


C>LINK HELLO+VMODE+DOSINT,MYPROG,,GRAPHICS; <Enter> 


This command would link the files HELLO.OBJ, VMODE. OBJ, and 
DOSINT.OBJ, searching the library file GRAPHICS.LIB to resolve any ref- 
erences to symbols not defined in the specified object files, and would 
produce a file named MYPROG. EXE. LINK uses the current drive and 
directory when they are not explicitly included in a filename; it will not 
automatically use the same drive and directory you specified for a pre- 
vious file in the same command line. 


By using the + operator or space characters in the libraries field, you can 
specify up to 32 library files to be searched. Each high-level-language 
compiler provides default libraries that are searched automatically during 
the linkage process if the linker can find them (unless they are explicitly 
excluded with the /NOD switch). LINK looks for libraries first in the cur- 
rent directory of the default disk drive, then along any paths that were 
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provided in the command line, and finally along the path(s) specified by 
the LIB variable if it is present in the environment. 


LINK accepts several optional switches as part of the command line or at 
the end of any interactive prompt. Figure 4-4 lists these switches. The 
number of switches available and their actions vary among different ver- 
sions of LINK. See your Microsoft Object Linker instruction manual for 
detailed information about your particular version. 


Switch Full form 


/A:n 


/B 


/CO 


/CP 


/DO 
/DS 


/E 
A 


/HE 
/HI 
/I 


/ALIGNMENT: 7 


/BATCH 


/CODEVIEW 


/CPARMAXALLOC 


/DOSSEG 


/DSALLOCATE 


/EXEPACK 


/FARCALLTRANSLATION 


/HELP 
/HIGH 
/INFORMATION 


Meaning 


Set segment sector alignment factor. N must be 
a power of 2 (default = 512). Not related to 
logical-segment alignment (BYTE, WORD, 
PARA, PAGE, and so forth). Relevant to 
segmented executable files (Microsoft 
Windows and MS OS/2) only. 

Suppress linker prompt if a library cannot be 
found in the current directory or in the 
locations specified by the LIB environment 
variable. 

Include symbolic debugging information in the 
.EXE file for use by CodeView. 

Set the field in the .EXE file header controlling 
the amount of memory allocated to the 
program in addition to the memory required 
for the program’s code, stack, and initialized 
data. 

Use standard Microsoft segment naming and 
ordering conventions. 

Load data at high end of the data segment. 
Relevant to real-mode programs only. 

Pack executable file by removing sequences of 
repeated bytes and optimizing relocation 
table. 

Optimize far calls to labels within the same 
physical segment for speed by replacing 
them with near calls and NOPs. 

Display information about available options. 

Load program as high in memory as possible. 

Display information about progress of linking, 
including pass numbers and the names of 
object files being linked. 


(continued) 


Figure 4-4. Switches accepted by the Microsoft Object Linker (LINK) version 5.0. 
Earlier versions use a subset of these switches. Note that any abbreviation for a switch 
is acceptable as long as it is sufficient to specify the switch uniquely. 
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Switch Full form 


/INC 


/MI:n] 


/NOD 


/PACL: 1] 


/INCREMENTAL 


/LINENUMBERS 


/MAPI:”] 


/NODEFAULTLIBRARYSEARCH 


/NOEXTENDEDDICTSEARCH 


/NOFARCALLTRANSLATION 
/NOGROUPASSOCIATION 
/NOIGNORECASE 
/NONULLSDOSSEG 
/NOPACKCODE 


/OVERLAYINTERRUPT: 


/PACKCODE!:7] 


/PADC:n /PADCODE:n 
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Meaning 


Force production of .SYM and .ILK files for 
subsequent use by ILINK (incremental 
linker). May not be used with /EXEPACK. 
Relevant to segmented executable files 
(Microsoft Windows and MS OS/2) only. 

Write address of the first instruction that 
corresponds to each source-code line to the 
map file. Has no effect if the compiler does 
not include line-number information in the 
object module. Force creation of a map file. 

Force creation of a .MAP file listing all public 
symbols, sorted by name and by location. 
The optional value 7 is the maximum 
number of symbols that can be sorted 
(default = 2048); when n is supplied, the 
alphabetically sorted list is omitted. 

Skip search of any default compiler libraries 
specified in the .OBJ file. 

Ignore extended library dictionary Cif it is 
present). The extended dictionary ordinarily 
provides the linker with information about 
inter-module dependencies, to speed up 
linking. 

Disable optimization of far calls to labels 
within the same segment. 

Ignore group associations when assigning 
addresses to data and code items. 

Do not ignore case in names during linking. 

Arrange segments as for /DOSSEG but do not 
insert 16 null bytes at start of _TEXT 
segment. 

Do not pack contiguous logical code segments 
into a single physical segment. 

Use interrupt number 7 with the overlay 
manager supplied with some Microsoft 
high-level languages. 

Pack contiguous logical code segments into a 
single physical code segment. The optional 
value n is the maximum size for each 
packed physical code segment (default = 
65,536 bytes). Segments in different groups 
are not packed. 

Add n filler bytes to end of each code module 
so that a larger module can be inserted later 
with ILINK. Relevant to segmented execut-. 
able files (Windows and MS OS/2) only. 


(continued) 
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Switch Full form Meaning 


/PADD:n /PADDATA:n Add n filler bytes to end of each data module 
so that a larger module can be inserted later 
with ILINK. Relevant to segmented execut- 
able files (Microsoft Windows and MS OS/2) 


only. 
/PAU /PAUSE . Pause during linking, allowing a change of 
disks before .EXE file is written. 
/SE:n /SEGMENTS:n Set maximum number of segments in linked 
program (default = 128). 
/ST:n /STACK:n Set stack size of program in bytes; ignore stack 


segment size declarations within object 
modules and definition file. 

/W /WARNFIXUP Display warning messages for offsets relative 
to a segment base that is not the same as 
the group base. Relevant to segmented 
executable files (Microsoft Windows and 
MS OS/2) only. 


The EXE2BIN Utility 


The EXE2BIN utility (EXE2BIN.EXE) transforms a .EXE file created by 
LINK into an executable .COM file, if the program meets the following 
prerequisites: 


= It cannot contain more than one declared segment and cannot 
define a stack. 


® It must be less than 64 KB in length. 
It must have an origin at 0100H. 


a The first location in the file must be specified as the entry point 
in the source code’s END directive. 


Although .COM files are somewhat more compact than .EXE files, you 
should avoid using them. Programs that use separate segments for code, 
data, and stack are much easier to port to protected-mode environments 
such as MS OS/2; in addition, .COM files do not support the symbolic 
debugging information used by CodeView. 


Another use for the EXE2BIN utility is to convert an installable device 
driver—after it is assembled and linked into a .EXE file—into a memory- 
image .BIN or .SYS file with an origin of zero. This conversion is required 
in MS-DOS version 2, which cannot load device drivers as .EXE files. The 
process of writing an installable device driver is discussed in more detail 
in Chapter 14. 
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Unlike most of the other programming utilities, EXE2BIN does not have 
an interactive mode. It always takes its source and destination filenames, 
separated by spaces, from the MS-DOS command line, as follows: 


EXE2BIN sourcefile |destinationfile] 


If you do not supply the source-file extension, it defaults to .EXE; the 
destination-file extension defaults to .BIN. If you do not specify a name 
for the destination file, EXE2BIN gives it the same name as the source file, 
with a .BIN extension. 


For example, to convert the file HELLO.EXE into HELLO.COM, you would 
use the following command line: 


C>EXE2BIN HELLO.EXE HELLO.COM <Enter> 


The EXE2BIN program also has other capabilities, such as pure binary 
conversion with segment fixup for creating program images to be placed 
in ROM; but because these features are rarely used during MS-DOS appli- 
cation development, they will not be discussed here. 


The CREF Utility 


The CREF cross-reference utility CREF.EXE processes a .CRF file pro- 
duced by MASM, creating an ASCII text file with the default extension 
-REF. The file contains a cross-reference listing of all symbols declared in 
the program and the line numbers in which they are referenced. (See 
Figure 4-5.) Such a listing is very useful when debugging large assembly- 
language programs with many interdependent procedures and variables. 


CREF may be supplied with its parameters interactively or in a single com- 
mand line. If you enter the utility name alone, CREF prompts you for the 
input and output filenames, as shown in the following example: 


C>CREF <Enter> 


Microsoft (R) Cross-Reference Utility Version 5.10 
Copyright (C) Microsoft Corp 1981-1985, 1987. All rights reserved. 


Cross-reference [.CRF]: HELLO <Enter> 
Listing [HELLO.REF]: 


15 Symbols 


C> 
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rence Version 5.10 | Thu May 26 11:09:34 1988 
V0 on terminal 


Figure 4-5. Cross-reference listing HELLO.REF produced by the CREF utility from 
the file HELLO.CRF, for the HELLO.EXE program example from Chapter 3. The sym- 
bols declared in the program are listed on the left in alphabetic order. To the right of 
each symbol is a list of all the lines where that symbol is referenced. The number with 
a # sign after it denotes the line where the symbol is declared. Numbers followed by a 
+ sign indicate that the symbol is modified at the specified line. The line numbers 
given in the cross-reference listing correspond to the line numbers generated by the 
assembler in the program-listing (LST) file, not to any physical line count in the origi- 
nal source file. 


The parameters may also be entered in the command line in the following 
form: | 


CREF CRF_/ile, listing_ file 


For example, the command-line equivalent to the preceding interactive 
session 1S: 


C>CREF HELLO,HELLO <Enter> 
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If CREF cannot find the specified .CRF file, it displays an error message. 
Otherwise, it leaves the cross-reference listing in the specified file on the 
disk. You can send the file to the printer with the COPY command, in the 
following form: 


COPY listing_file PRN: 


You can also send the cross-reference listing directly to a character device 
as it is generated by responding to the Listing prompt with the name of 
the device. 


The Microsoft Library Manager 


Although the object modules that are produced by MASM or by high- 
level-language compilers can be linked directly into executable load mod- 
ules, they can also be collected into special files called object-module 
libraries. The modules in a library are indexed by name and by the public 
symbols they contain, so that they can be extracted by the linker to satisfy 
external references in a program. 


The Microsoft Library Manager (LIB) is distributed as the file LIB.EXE. LIB 
creates and maintains program libraries, adding, updating, and deleting 
object files as necessary. LIB can also check a library file for internal con- 
sistency or print a table of its contents (Figure 4-6). 


LIB follows the command conventions of most other Microsoft program- 
ming tools. You must supply it with the name of a library file to work on, 
one or more operations to perform, the name of a listing file or device, 
and (optionally) the name of the output library. If you do not specify a 
name for the output library, LIB gives it the same name as the input library 
and changes the extension of the input library to .BAK. 


The LIB operations are simply the names of object files, with a prefix 
character that specifies the action to be taken: 


Prefix Meaning 

- Delete an object module from the library. 

* Extract a module and place it in a separate .OBJ file. 

+ Add an object module or the entire contents of another library 
to the library. 


You can combine command prefixes. For example, —+ replaces a module, 
and *— extracts a module into a new file and then deletes it from the 
library. 
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Figure 4-6. Extract from the table-of-contents listing produced by the Microsoft 
Library Manager (LIB) for the Microsoft C library SLIBC.LIB. The first part of the list- 
ing is an alphabetic list of all public names declared in all of the modules in the 
library. Each name is associated with the object module to which it belongs. The sec- 
ond part of the listing is an alphabetic list of the object-module names in the library, 
each followed by its offset within the library file and the actual size of the module in 


bytes. The entry for each module is followed by a summary of the public names that 
are declared within it. 


When you invoke LIB with its name alone, it requests the other informa- 
tion it needs interactively, as shown in the following example: 


C>LIB <€Enter> 


Microsoft (R) Library Manager Version 3.08 
Copyright (C) Microsoft Corp 1983-1987. Al} rights reserved. 


Library name: SLIBC <Enter> 
Operations: +VIDEO <Enter> 

List file: SLIBC.LST <Enter> 
Output library: SLIBC2 <Enter> 


C> 
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In this example, LIB added the object module VIDEO. OBJ to the library 
SLIBC.LIB, wrote a library table of contents into the file SIIBC.LST, and 
named the resulting new library SLIBC2.LIB. 


The Library Manager can also be run with a command line of the follow- 
ing form: 


LIB library [commands],llist),{newlibrary] 


For example, the following command line is equivalent to the preceding 
interactive session: 


C>LIB SLIBC +VIDEO,SLIBC.LST,SLIBC2: <Enter> 


As with the other Microsoft utilities, a semicolon at the end of the com- 
mand line causes LIB to use the default responses for any parameters that 
are omitted. 


Like LINK, LIB can also accept its commands from a response file. The 
contents of the file are lines of text that correspond exactly to the 
responses you would give LIB interactively. You specify the name of the 
response file in the command line with a leading @ character, as follows: 


LIB @filename 


LIB has only three switches: /I (/IGNORECASE), /N (/NOIGNORECASE), 
and /PAGESIZE:number. The /IGNORECASE switch is the default. The 
/NOIGNORECASE switch causes LIB to regard as distinct any symbols 
that differ only in the case of their component letters. You should place the 
/PAGESIZE switch, which defines the size of a unit of allocation space for 
a given library, immediately after the library filename. The library page 
size is in bytes and must be a power of 2 between 16 and 32,768 (16, 32, 64, 
and so forth); the default is 16 bytes. Because the index to a library is al- 
ways a fixed number of pages, setting a larger page size allows you to store 
more object modules in that library; on the other hand, it will result in 
more wasted space within the file. 


The MAKE Utility 


The MAKE utility (MAKE.EXE) compares dates of files and carries out 
commands based on the result of that comparison. Because of this single, 
rather basic capability, MAKE can be used to maintain complex programs 
built from many modules. The dates of source, object, and executable files 
are simply compared in a logical sequence; the assembler, compiler, 
linker, and other programming tools are invoked as appropriate. 
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The MAKE utility processes a plain ASCII text file called, as you might ex- 
pect, a make file. You start the utility with a command-line entry in the 
following form: 


MAKE makefile [options] 


By convention, a make file has the same name as the executable file that is 
being maintained, but without an extension. The available MAKE 
switches are listed in Figure 4-7. 


A simple make file contains one or more dependency statements sepa- 
rated by blank lines. Each dependency statement can be followed by a list 
of MS-DOS commands, in the following form: 


targetfile : sourcefile ... 


command 


command 


If the date and time of any source file are later than those of the target file, 
the accompanying list of commands is carried out. You may use comment 
lines, which begin with a # character, freely in a make file. MAKE can also 
process inference rules and macro definitions. For further details on these 
advanced capabilities, see the Microsoft or IBM documentation. 


a 


Switch Meaning 

/D Display last modification date of each file as it is processed. 

/I Ignore exit (return) codes returned by commands and programs 
executed asa result of dependency statements. 

/N Display commands that would be executed as a result of 
dependency statements but do not execute those commands. 

/S Do not display commands as they are executed. 


/X<filename> _ Direct error messages from MAKE, or any program that MAKE 
runs, to the specified file. If filename is a hyphen (-), direct 
error messages to the standard output. 


nn ttt 


Figure 4-7. Switches for the MAKE utility. 
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A Complete Example 


Let’s put together everything we’ve learned about using the MS-DOS pro- 
gramming tools so far. Figure 4-8 shows a sketch of the overall process of 
building an executable program. 


Assume that we have the source code for the HELLO.EXE program from 
Chapter 3 in the file HELLO. ASM. To assemble the source program into 
the relocatable object module HELLO.OBJ with symbolic debugging infor- 
mation included, also producing a program listing in the file HELLO. LST 
and a cross-reference data file HELLO. CRF, we would enter 


COMASM /C /L /Zi /T HELLO; <Enter> 


To convert the cross-reference raw-data file HELLO.CRF into a cross- 
reference listing in the file HELLO.REF, we would enter 


C>CREF HELLO,HELLO <Enter> 


z 

MASM C or other 

: source-code | HLL source- 

file : code file 

_ eRe UE TR Eases BONE Dae Tea 
MASM Compiler 


Relocatable 
object-module 
file OBJ) 


Meee 


Ea Sanaa 


ee 


Object-module 
libraries 
(.LIB) 


LINK Executable 
: program 


Be 


a RE 


oe 


Executable 
program 


HLL 


runtime 
libraries 


a ’ or Daa Atenas Be iA 
SSAA Ua EOE TOR CERRO oO 


Figure 4-8. Creation of an MS-DOS application program, from source code to exe- 
cutable file. 
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To convert the relocatable object file HELLO.OBJ into the executable file 
HELLO.EXE, creating a load map in the file HELLO.MAP and appending 
symbolic debugging information to the executable file, we would enter 


C>LINK /MAP /CODEVIEW HELLO; <Enter> 


We could also automate the entire process just described by creating a 
make file named HELLO (with no extension) and including the following 
instructions: 


hello.obj : hello.asm 
masm /C /L /Zi /T hello; 
cref hello,hello 


hello.exe : hello.obj 
link /MAP /CODEVIEW hello; 


Then, when we have made some change to HELLO.ASM and want to 
rebuild the executable HELLO.EXE file, we need only enter 


C>MAKE HELLO <Enter> 
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MASM Tutorials 


Assembly Language Primer for the IBM PC and XT, by Robert Lafore. New 
American Library, New York, NY, 1984. ISBN 0-452-25711-5. 


8086/8088/80286 Assembly Language, by Leo Scanlon. Brady Books, 
Simon and Schuster, New York, NY, 1988. ISBN 0-13-246919-7. 
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Chapter 5 


The fundamental means of user input under MS-DOS is the keyboard. 
This follows naturally from the MS-DOS command-line interface, whose 
lineage can be traced directly to minicomputer operating systems with 
Teletype consoles. During the first few years of MS-DOS’s existence, when’ 
8088/8086-based machines were the norm, nearly every popular applica- 
tion program used key-driven menus and text-mode displays. 


However, as high-resolution graphics adapters (and 80286/80386-based 
machines with enough power to drive them) have become less expensive, 
programs that support windows and a graphical user interface have 
steadily grown more popular. Such programs typically rely on a pointing 
device such as a mouse, stylus, joystick, or light pen to let the user navi- 
gate in a “point-and-shoot” manner, reducing keyboard entry to a 
minimum. As a result, support for pointing devices has become an impor- 
tant consideration for all software developers. 


Keyboard Input Methods 


Applications running under MS-DOS on IBM PC-compatible machines 
can use several methods to obtain keyboard input: 


MS-DOS handle-oriented functions 
2 MS-DOS traditional character functions 
IBM ROM BIOS keyboard-driver functions 


These methods offer different degrees of flexibility, portability, and hard- 
ware independence. 


The handle, or stream-oriented, functions are philosophically derived 
from UNIX/XENIX and were first introduced in MS-DOS version 2.0. A 
program uses these functions by supplying a handle, or token, for the 
desired device, plus the address and length of a buffer. 


When a program begins executing, MS-DOS supplies it with predefined 
handles for certain commonly used character devices, including the 


keyboard: 

Caen Se SS 
Handle Device name Opened to 

0 Standard input (stdin) CON 

1 Standard output (stdout) CON 

2 Standard error (stderr) CON 

3 Standard auxiliary (stdaux) AUX 

4 Standard printer (stdprn) PRN 
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These handles can be used for read and write operations without further 
preliminaries. A program can also obtain a handle for a character device 
by explicitly opening the device for input or output using its logical name 
(as though it were a file). The handle functions support I/O redirection, 
allowing a program to take its input from another device or file instead of 
the keyboard, for example. Redirection is discussed in detail in Chapter 15. 


The traditional character-input functions are a superset of the character 
I/O functions that were present in CP/M. Originally included in MS-DOS 
simply to facilitate the porting of existing applications from CP/M, they 
are still widely used. In MS-DOS versions 2.0 and later, most of the tradi- 
tional functions also support I/O redirection (although not as well as the 
handle functions do). 


Use of the IBM ROM BIOS keyboard functions presupposes that the pro- 
gram is running on an IBM PC-compatible machine. The ROM BIOS key- 
board driver operates at a much more primitive level than the MS-DOS 
functions and allows a program to circumvent I/O redirection or MS- 
DOS’s special handling of certain control characters. Programs that use 
the ROM BIOS keyboard driver are inherently less portable than those that 
use the MS-DOS functions and may interfere with the proper operation of 
other programs; many of the popular terminate-and-stay-resident (TSR) 
utilities fall into this category. 


Keyboard Input with Handles 


The principal MS-DOS function for keyboard input using handles is Int 
21H Function 3FH (Read File or Device). The parameters for this function 
are a handle, the segment and offset of a buffer, and the length of the 
buffer. (For a more detailed explanation of this function, see Section II of 
this book, “MS-DOS Functions Reference.”) 


As an example, let’s use the predefined standard input handle (0) and Int 
21H Function 3FH to read a line from the keyboard: 


(continued) 
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(continued) 


When control returns from Int 21H Function 3FH, the carry flag is clear if 
the function was successful, and AX contains the number of characters 
read. If there was an error, the carry flag is set and AX contains an error 
code; however, this should never occur when reading the keyboard. 


The standard input is redirectable, so the code just shown is not a 
foolproof way of obtaining input from the keyboard. Depending upon 
whether a redirection parameter was included in the command line by 
the user, program input might be coming from the keyboard, a file, 
another character device, or even the bit bucket (NUL device). To bypass 
redirection and be absolutely certain where your input is coming from, 
you can ignore the predefined standard input handle and open the con- 
sole as though it were a file, using the handle obtained from that open 
operation to perform your keyboard input, as in the fol lowing example: 


“buffers db 
fname db 


(continued) 
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When a programmer uses Int 21H Function 3FH to read from the key- 
board, the exact result depends on whether MS-DOS regards the handle to 
be in ASCII mode or binary mode (sometimes known as cooked mode and 
raw mode). ASCII mode is the default, although binary mode can be 
selected with Int 21H Function 44H (IOCTL) when necessary. 


In ASCII mode, MS-DOS initially places characters obtained from the key- 
board in a 128-byte internal buffer, and the user can edit the input with the 
Backspace key and the special function keys. MS-DOS automatically 
echoes the characters to the standard output, expanding tab characters to 
spaces (although they are left as the ASCII code 09H in the buffer). The 
Ctrl-C, Ctrl-S, and Ctrl-P key combinations receive special handling, and 
the Enter key is translated to a carriage return—linefeed pair. When the user 
presses Enter or Ctrl-Z, MS-DOS copies the requested number of charac- 
ters (or the actual number of characters entered, if less than the number 
requested) out of the internal buffer into the calling program’s buffer. 


In binary mode, MS-DOS never echoes input characters. It passes the Ctrl- 
C, Ctrl-S, Ctrl-P, and Ctrl-Z key combinations and the Enter key through to 
the application unchanged, and Int 21H Function 3FH does not return 
control to the application until the exact number of characters requested 
has been received. 


Ctrl-C checking is discussed in more detail at the end of this chapter. For 
now, simply note that the application programmer can substitute a custom 
handler for the default MS-DOS Ctrl-C handler and thereby avoid having 
the application program lose control of the machine when the user enters 
a Ctrl-C or Ctrl-Break. 


Keyboard Input with Traditional Calis 


The MS-DOS traditional keyboard functions offer a variety of character 
and line-oriented services with or without echo and Ctrl-C detection. 
These functions are summarized on the following page. 
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Int 21H Function Action Ctrl-C checking 


01H Keyboard input with echo Yes 
06H Direct console I/O No 
07H Keyboard input without echo No 
08H Keyboard input without echo Yes 
OAH Buffered keyboard input Yes 
OBH Input-status check Yes 
0CH Input-buffer reset and input Varies 


—_—_—_—.,eoro ee ea — 


In MS-DOS versions 2.0 and later, redirection of the standard input affects 
all these functions. In other words, they act as though they were special 
cases of an Int 21H Function 3FH call using the predefined standard input 
handle (0). 


The character-input functions (01H, 06H, 07H, and 08H) all return a char- 
acter in the AL register. For example, the following sequence waits until a 
key is pressed and then returns it in AL: 


The character-input functions differ in whether the input is echoed to the 
screen and whether they are sensitive to Ctrl-C interrupts. Although MS- 
DOS provides no pure keyboard-status function that is immune to Ctrl-C, 
a program can read keyboard status (somewhat circuitously) without in- 
terference by using Int 21H Function 06H. Extended keys, such as the IBM 
PC keyboard’s special function keys, require two calls to a character-input 
function. 


As an alternative to single-character input, a program can use buffered- 
line input (Int 21H Function 0AH) to obtain an entire line from the key- 
board in one operation. MS-DOS builds up buffered lines in an internal 
buffer and does not pass them to the calling program until the user 
presses the Enter key. While the line is being entered, all the usual editing 
keys are active and are handled by the MS-DOS keyboard driver. You use 
Int 21H Function OAH as follows: 


(continued) 
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Int 21H Function OAH differs from Int 21H Function 3FH in several impor- 
tant ways. First, the maximum length is passed in the first byte of the 
buffer, rather than in the CX register. Second, the actual length is returned 
in the second byte of the structure, rather than in the AX register. Finally, 
when the user has entered one less than the specified maximum number 
of characters, MS-DOS ignores all subsequent characters and sounds a 
warning beep until the Enter key is pressed. 


For detailed information about each of the traditional keyboard-input 
functions, see Section II of this book, “MS-DOS Functions Reference.” 


Keyboard Input with ROM BIOS Functions 
Programmers writing applications for IBM PC compatibles can bypass the 


MS-DOS keyboard functions and choose from two hardware-dependent 
techniques for keyboard input. 


The first method is to call the ROM BIOS keyboard driver using Int 16H. 
For example, the following sequence reads a single character from the 
keyboard input buffer and returns it in the AL register: 


Int 16H Function 00H also returns the keyboard scan code in the AH 
register, allowing the program to detect key codes that are not ordinarily 
returned by MS-DOS. Other Int 16H services return the keyboard status 
(that is, whether a character is waiting) or the keyboard shift state (from 
the ROM BIOS data area 0000:0417H). For a more detailed explanation of 
ROM BIOS keyboard functions, see Section III of this book, “IBM ROM 
BIOS and Mouse Functions Reference.” 


Keyboard and Mouse Input 71 


You should consider carefully before building ROM BIOS dependence into 
an application. Although this technique allows you to bypass any I/O redi- 
rection that may be in effect, ways exist to do this without introducing de- 
pendence on the ROM BIOS. And there are real disadvantages to calling 
the ROM BIOS keyboard driver: 


a It always bypasses I/O redirection, which sometimes may not be 
desirable. 


a It is dependent on IBM PC compatibility and does not work correctly, 
unchanged, on some older machines such as the Hewlett-Packard 
TouchScreen or the Wang Professional Computer. 


# It may introduce complicated interactions with TSR utilities.. 


The other and more hardware-dependent method of keyboard input on 
an IBM PC is to write a new handler for ROM BIOS Int 09H and service the 
keyboard controller’s interrupts directly. This involves translation of scan 
codes to ASCII characters and maintenance of the type-ahead buffer. In 
ordinary PC applications, there is no reason to take over keyboard I/O at 
this level; therefore, I will not discuss this method further here. If you are 
curious about the techniques that would be required, the best reference is 
the listing for the ROM BIOS Int 09H handler in the IBM PC or PC/AT 
technical reference manual. 


Ctrl-C and Ctrl-Break Handlers 
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In the discussion of keyboard input with the MS-DOS handle and tradi- 
tional functions, I made some passing references to the fact that Ctrl-C en- 
tries can interfere with the expected behavior of those functions. Let’s 
look at this subject in more detail now. 


During most character I/O operations, MS-DOS checks for a Ctrl-C (ASCII 
code 03H) waiting at the keyboard and executes an Int 23H if one is 
detected. If the system break flag is on, MS-DOS also checks for a Ctrl-C 
entry during certain other operations (such as file reads and writes). Ordi- 
narily, the Int 23H vector points to a routine that simply terminates the 
currently active process and returns control to the parent process— 
usually the MS-DOS command interpreter. 


In other words, if your program is executing and you enter a Ctrl-C, acci- 
dentally or intentionally, MS-DOS simply aborts the program. Any files the 
program has opened using file control blocks will not be closed properly, 
any interrupt vectors it has altered may not be restored correctly, and if it 
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is performing any direct I/O operations (for example, if it contains an in- 
terrupt driver for the serial port), all kinds of unexpected events may 
occur. 


Although you can use a number of partially effective methods to defeat 
Ctrl-C checking, such as performing keyboard input with Int 21H Func- 
tions 06H and 07H, placing all character devices into binary mode, or 
turning off the system break flag with Int 21H Function 33H, none of these 
is completely foolproof. The simplest and most elegant way to defeat Ctrl- 
C checking is simply to substitute your own Int 23H handler, which can 
take some action appropriate to your program. When the program termi- 
nates, MS-DOS automatically restores the previous contents of the Int 23H 
vector from information saved in the program segment prefix. The follow- 
ing example shows how to install your own Ctrl-C handler (which in this 
case does nothing at all): 


The first part of the code (which alters the contents of the Int 23H vector) 
would be executed in the initialization part of the application. The han- 
dler receives control whenever MS-DOS detects a Ctrl-C at the keyboard. 
(Because this handler consists only of an interrupt return, the Ctrl-C will 
remain in the keyboard input stream and will be passed to the application 


when it requests a character from the keyboard, appearing on the screen 
as AC.) 


When an Int 23H handler is called, MS-DOS is in a stable state. Thus, the 
handler can call any MS-DOS function. It can also reset the segment regis- 
ters and the stack pointer and transfer control to some other point in the 
application without ever returning control to MS-DOS with an IRET. 
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On IBM PC compatibles, an additional interrupt handler must be taken 
into consideration. Whenever the ROM BIOS keyboard driver detects the 
key combination Ctrl-Break, it calls a handler whose address is stored in 
the vector for Int 1BH. The default ROM BIOS Int 1BH handler does 
nothing. MS-DOS alters the Int IBH vector to point to its own handler, 
which sets a flag and returns; the net effect is to remap the Ctrl-Break into 
a Ctrl-C that is forced ahead of any other characters waiting in the key- 
board buffer. 


Taking over the Int IBH vector in an application is somewhat tricky but 


extremely useful. Because the keyboard is interrupt driven, a press of Ctrl- 


Break lets the application regain control under almost any circum- 
stance— often, even if the program has crashed or is in an endless loop. 


You cannot, in general, use the same handler for Int 1BH that you use for 
Int 23H. The Int 1BH handler is more limited in what it can do, because it 
has been called as a result of a hardware interrupt and MS-DOS may have 
been executing a critical section of code at the time the interrupt was ser- 
viced. Thus, all registers except CS:IP are in an unknown state; they may 
have to be saved and then modified before your interrupt handler can exe- 
cute. Similarly, the depth of the stack in use when the Int 1BH handler is 
called is,inknown, and if the handler is to perform stack-intensive opera- 
tions, it may have to save the stack segment and the stack pointer and 
switch to a new stack that is known to have sufficient depth. 


In normal application programs, you should probably avoid retaining con- 
trol in an Int 1BH handler, rather than performing an IRET. Because of 
subtle differences among non-IBM ROM BlOSes, it is difficult to predict 
the state of the keyboard controller and the 8259 Programmable Interrupt 
Controller (PIC) when the Int IBH handler begins executing. Also, MS- 
DOS itself may not be in a stable state at the point of interrupt, a situation 
that can manifest itself in unexpected critical errors during subsequent I/O 
operations. Finally, MS-DOS versions 3.2 and later allocate a stack from an 
internal pool for use by the Int 09H handler. If the Int IBH handler never 
returns, the Int 09H handler never returns either, and repeated entries of 
Ctrl-Break will eventually exhaust the stack pool, halting the system. 


Because Int IBH is a ROM BIOS interrupt and not an MS-DOS interrupt, 
MS-DOS does not restore the previous contents of the Int 1BH vector 
when a program exits. If your program modifies this vector, it must save 
the original value and restore it before terminating. Otherwise, the vector 
will be left pointing to some random area in the next program that runs, 
and the next time the user presses Ctrl-Break a system crash is the best 
you can hope for. 
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Ctrl-C and Ctrl-Break Handlers and High-Level Languages 


Capturing the Ctrl-C and Ctrl-Break interrupts is straightforward when 
you are programming in assembly language. The process is only slightly 
more difficult with high-level languages, as long as you have enough infor- 
mation about the language’s calling conventions that you can link in a 
small assembly-language routine as part of the program. 


The BREAK.ASM listing in Figure 5-1 contains source code for a Ctrl- 
Break handler that can be linked with small-model Microsoft C programs 
running on an IBM PC compatible. The short C program in Figure 5-2 
demonstrates use of the handler. (This code should be readily portable to 
other C compilers.) 


(continued) 


Figure 5-1. BREAK.ASM: A Ctrl-C and Ctrl-Break interrupt handler that can be 
linked with Microsoft C programs. 
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Figure 5-1. continued 
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Figure 5-1. continued 


push 
pop 
mov 


mov. 


mov. 


int 


PoP 
- pop. 
pop 


oc pop 


ret 


cs 
dso ee 
dx, offset ete 


ax, 02523h oe 


21h 


ax, Q251bh 
21h 


sie | 
dig o> on 8 
ds 


bp 


_capture endp _ 


“public 
_Telease proc 


“pude 
push 


push 


push — 


Tds 


mov 
int. 


Ids 


mov 
int 


pop 
pop 
pop 
pop 
ret 


vee 


near 


release. 


bp 


ds 
di 


dx,cs:intlb 


ax,251bh 
21h 
dx,cs:int23_ 


ax, 2523h 


21h. 


Sie 
di 
ds 
bp 


ctrlbrk 


~=e 


save registers. 


“restore registers 


set DS:DX = address ae 
of new handler 


set int 1bh vector 


restore registers 


discard stack frame 
and return to caller Pee 


and Ctrl- Break handlers 


get address. of “previous 
ing Ibh handler — 


eae int ibh ee 


A get address of srevitus oe 


int 23h nagever 


set int 2 23h vector 


and return to caller 


(continued) 


Keyboard and Mouse Input 77 


Figure 5-1. continued 
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Figure 5-2. TRYBREAK.C: A simple Microsoft C program that demonstrates use of the 
interrupt handler BREAK.ASM from Figure 5-1. 


78 Programming for MS-DOS 


a 5-2. COREG 


~MASM- Mx BREAK; ae 
CL TRYBREAK. c BREAK. OBJ 


* / 
1 */ 


*/ 


“puts("Press the Esc Ney to exit TRYBREAK. Ans 


eapturecamagy: - os install new Ctrl: & and 


check: ‘for key prees: x / 
(MS- pos sees Ctrl-C 
: when keyboard polled): +/ 


hit = kbhitO: 


. re ds true, an ee ops 
interrupt has occurred */ 
puts("\ncontrot- “Break detected. \n"); pe 
ot* reset interrupt flag */ 


if (flag I--0) oe 


ts if any key waiting oy) 


c = getch(); [x read key, exit if Esc #/ 
po Tf CC & Ox7#) — 0x1b) break; — 
oe putch(c) ee as othe 


release(); | /* restore orignal ctrl- C 
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"puts ("\n\nTRYBREAK has released interrupt vectors"); 
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In the example handler, the procedure named capture is called with the 
address of an integer variable within the C program. It saves the address of 
the variable, points the Int 1BH and Int 23H vectors to its own interrupt 
handler, and then returns. 


When MS-DOS detects a Ctrl-C or Ctrl-Break, the interrupt handler sets 
the integer variable within the C program to true (1) and returns. The C 
program can then poll this variable at its leisure. Of course, to detect more 
than one Ctrl-C, the program must reset the variable to zero again. 


The procedure named release simply restores the Int 1BH and Int 23H 
vectors to their original values, thereby disabling the interrupt handler. 
Although it is not strictly necessary for release to do anything about Int 
23H, this action does give the C program the option of restoring the 
default handler for Int 23H without terminating. 


Pointing Devices 


Device drivers for pointing devices are supplied by the hardware manu- 
facturer and are loaded with a DEVICE statement in the CONFIG.SYS file. 
Although the hardware characteristics of the available pointing devices 
differ greatly, nearly all of their drivers present the same software inter- 
face to application programs: the Int 33H protocol used by the Microsoft 
Mouse driver. Version 6 of the Microsoft Mouse driver (which was current 
as this was written) offers the following functions: 


Function Meaning 

00H Reset mouse and get status. 

01H Show mouse pointer. 

02H Hide mouse pointer. 

03H Get button status and pointer position. 
04H Set pointer position. 

05H Get button-press information. 

06H Get button-release information. 

07H Set horizontal limits for pointer. 

08H Set vertical limits for pointer. 

09H Set graphics pointer type. 

OAH Set text pointer type. 

0OBH Read mouse-motion counters. 

0CH Install interrupt handler for mouse events. 
ODH Turn on light pen emulation. 

OEH Turn off light pen emulation. 

OFH Set mickeys to pixel ratio. 

10H Set pointer exclusion area. 
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Function Meaning 

13H Set double-speed threshold. 

14H Swap mouse-event interrupt routines. 
15H Get buffer size for mouse-driver state. 
16H Save mouse-driver state. 

17H Restore mouse-driver state. 

18H Install alternate handler for mouse events. 
19H Get address of alternate handler. 

1AH Set mouse sensitivity. 

1BH Get mouse sensitivity. 

1CH Set mouse interrupt rate. 

1DH Select display page for pointer. 

1EH Get display page for pointer. 

1FH Disable mouse driver. 

20H Enable mouse driver. 

21H Reset mouse driver. 

22H Set language for mouse-driver messages. 
23H Get language number. 

24H Get driver version, mouse type, and IRQ number. 


Although this list of mouse functions may appear intimidating, the aver- 
age application will only need a few of them. 


A program first calls Int 33H Function 00H to initialize the mouse driver 
for the current display mode and to check its status. At this point, the 
mouse is “alive” and the application can obtain its state and position; how- 
ever, the pointer does not become visible until the process calls Int 33H 
Function 01H. 


The program can then call Int 33H Functions 03H, 05H, and 06H to moni- 
tor the mouse position and the status of the mouse buttons. Alternatively, 
the program can register an interrupt handler for mouse events, using Int 
33H Function OCH. This latter technique eliminates the need to poll the 
mouse driver; the driver will notify the program by calling the interrupt 
handler whenever the mouse is moved or a button is pressed or released. 


When the application is finished with the mouse, it can call Int 33H Func- 
tion 02H to hide the mouse pointer. If the program has registered an inter- 
rupt handler for mouse events, it should disable further calls to the handler 
by resetting the mouse driver again with Int 33H Function 00H. 


For a complete description of the mouse-driver functions, see Section ITI 
of this book, “IBM ROM BIOS and Mouse Functions Reference.” Figure 5-3 
shows a small demonstration program that polls the mouse continually, to 
display its position and status. 
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Figure 5-3. MOUDEMO.C: A simple Microsoft C program that polls the mouse and 
continually displays the coordinates of the mouse pointer in the upper left corner of 
the screen. The program uses the ROM BIOS video driver, which is discussed in Chap- 
ter 6, to clear the screen and position the text cursor. 
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Chapter 6 


Video Display 


The visual presentation of an application program is one of its most im- 
portant elements. Users frequently base their conclusions about a pro- 
gram’s performance and “polish” on the speed and attractiveness of its 
displays. Therefore, a feel for the computer system’s display facilities and 
capabilities at all levels, from MS-DOS down to the bare hardware, is 
important to you as a programmer. 


Video Display Adapters 


The video display adapters found in IBM PC-compatible computers have 
a hybrid interface to the central processor. The overall display characteris- 
tics, such as vertical and horizontal resolution, background color, and 
palette, are controlled by values written to I/O ports whose addresses are 
hardwired on the adapter, whereas the appearance of each individual 
character or graphics pixel on the display is controlled by a specific loca- 
tion within an area of memory called the regen buffer or refresh buffer. 
Both the CPU and the video controller access this memory; the software 
updates the display by simply writing character codes or bit patterns di- 
rectly into the regen buffer. (This is called memory-mapped I/O.) 


The following adapters are in common use as this book is being written: 


Monochrome/Printer Display Adapter (MDA). Introduced with the 
original IBM PC in 1981, this adapter supports 80-by-25 text display on 
a green (monochrome) screen and has no graphics capabilities at all. 


Color/Graphics Adapter (CGA). Also introduced by IBM in 1981, this 
adapter supports 40-by-25 and 80-by-25 text modes and 320-by-200, 
4-color or 640-by-200, 2-color graphics (all-points-addressable, or APA) 
modes on composite or digital RGB monitors. 


@ Enhanced Graphics Adapter (EGA). Introduced by IBM in 1985 and 
upwardly compatible from the CGA, this adapter adds support for 640- 
by-350, 16-color graphics modes on digital RGB monitors. It also sup- 
ports an MDA-compatible text mode. 


Multi-Color Graphics Array (MCGA). Introduced by IBM in 1987 with 
the Personal System/2 (PS/2) models 25 and 30, this adapter is partially 
compatible with the CGA and EGA and supports 640-by-480, 2-color or 
320-by-200, 256-color graphics on analog RGB monitors. 


Video Graphics Array (VGA). Introduced by IBM in 1987 with the PS/2 
models 50, 60, and 80, this adapter is upwardly compatible from the 
EGA and supports 640-by-480, 16-color or 320-by-200, 256-color 
graphics on analog RGB monitors. It also supports an MDA-compatible 
text mode. 
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# Hercules Graphics Card, Graphics CardPlus, and InColor Cards. These 
are upwardly compatible from the MDA for text display but offer 
graphics capabilities that are incompatible with all of the IBM adapters. 


The locations of the regen buffers for the various IBM PC—compatible 
adapters are shown in Figure 6-1. 
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Figure 6-1. Memory diagram of an IBM PC—compatible personal computer, showing 
the locations of the regen buffers for various adapters. 
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Support Considerations 


MS-DOS offers several functions to transfer text to the display. Version 1 
supported only Teletype-like output capabilities; version 2 added an op- 
tional ANSI console driver to allow the programmer to clear the screen, 
position the cursor, and select colors and attributes with standard escape 
sequences embedded in the output. Programs that use only the MS-DOS 
functions will operate properly on any computer system that runs MS- 
DOS, regardless of the level of IBM hardware compatibility. 


On IBM PC-compatible machines, the ROM BIOS contains a video driver 
that programs can invoke directly, bypassing MS-DOS. The ROM BIOS 
functions allow a program to write text or individual pixels to the screen 
or to select display modes, video pages, palette, and foreground and back- 
ground colors. These functions are relatively efficient (compared with the 
MS-DOS functions, at least), although the graphics support is primitive. 


Unfortunately, the display functions of both MS-DOS and the ROM BIOS 
were designed around the model of a cursor-addressable terminal and 
therefore do not fully exploit the capabilities of the memory-mapped, 
high-bandwidth display adapters used on IBM PC—compatible machines. 
As a result, nearly every popular interactive application with full-screen 
displays or graphics capability ignores both MS-DOS and the ROM BIOS 
and writes directly to the video controller's registers and regen buffer. 


Programs that control the hardware directly are sometimes called “ill- 
behaved,” because they are performing operations that are normally 
reserved for operating-system device drivers. These programs are a 
severe management problem in multitasking real-mode environments 
such as DesqView and Microsoft Windows, and they are the main reason 
why such environments are not used more widely. It could be argued, 
however, that the blame for such problematic behavior lies not with the 
application programs but with the failure of MS-DOS and the ROM 
BlOS—even six years after the first appearance of the IBM PC—to pro- 
vide display functions of adequate range and power. 


MS-DOS Display Functions 


Under MS-DOS versions 2.0 and later, the preferred method for sending 
text to the display is to use handle-based Int 21H Function 40H (Write File 
or Device). When an application program receives control, MS-DOS has 
already assigned it handles for the standard output (1) and standard error 
(2) devices, and these handles can be used immediately. For example, the 
sequence at the top of the following page writes the message hello to the 
display using the standard output handle. 
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If there is no error, the function returns the carry flag cleared and the 
number of characters actually transferred in register AX. Unless a Ctrl-Z 
is embedded in the text or the standard output is redirected to a disk file 


and the disk is full, this number should equal the number of characters 
requested. 


As in the case of keyboard input, the user’s ability to specify command- 
line redirection parameters that are invisible to the application means that 
if you use the predefined standard output handle, you can’t always be sure 
where your output is going. However, to ensure that your output actually 
goes to the display, you can use the predefined standard error handle, 
which is always opened to the CON (logical console) device and is not 
redirectable. 


As an alternative to the standard output and standard error handles, you 
can bypass any output redirection and open a separate channel to CON, 
using the handle obtained from that open operation for character output. 


For example, the following code opens the console display for output and 
then writes the string hello to it: 


(continued) 
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As with the keyboard input functions, MS-DOS also supports traditional 
display functions that are upwardly compatible from the corresponding 
CP/M output calls: 


Int 21H Function 02H sends the character in the DL register to the stan- 
dard output device. It is sensitive to Ctrl-C interrupts, and it handles 
carriage returns, linefeeds, bell codes, and backspaces appropriately. 


@ Int 21H Function 06H transfers the character in the DL register to the 
standard output device, but it is not sensitive to Ctrl-C interrupts. You 
must take care when using this function, because it can also be used 
for input and for status requests. 


@ Int 21H Function 09H sends a string to the standard output device. The 
string is terminated by the $ character. 


With MS-DOS version 2 or later, these three traditional functions are con- 
verted internally to handle-based writes to the standard output and thus 
are susceptible to output redirection. 


The.sequence at the top of the following page sounds a warning beep by 
sending an ASCII bell code (07H) to the display driver using the tradi- 
tional character-output call Int 21H Function 02H. 
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The following sequence uses the traditional string-output call Int 21H 
Function 09H to display a string: 


Note that MS-DOS detects the $ character as a terminator and does not 
display it on the screen. 


Screen Control with MS-DOS Functions 


With version 2.0 or later, if MS-DOS loads the optional device driver 
ANSLSYS in response to a DEVICE directive in the CONFIG.SYS file, pro- 
grams can clear the screen, control the cursor position, and select fore- 
ground and background colors by embedding escape sequences in the 
text output. Escape sequences are so called because they begin with an 
escape character (1BH), which alerts the driver to intercept and interpret 


‘the subsequent characters in the sequence. When the ANSI driver is not 


loaded, MS-DOS simply passes the escape sequence to the display like any 
other text, usually resulting in a chaotic screen. 


The escape sequences that can be used with the ANSI driver for screen 
control are a subset of those defined in the ANSI 3.64-1979 Standard. 
These standard sequences are summarized in Figure 6-2. Note that case is 


Video Display 


91 


significant for the last character in an escape sequence and that numbers 
must always be represented as ASCII digit strings, not as their binary 
values. (A separate set of escape sequences supported by ANSLSYS, but 
not compatible with the ANSI standard, may be used for reprogramming 
and remapping the keyboard.) 


ee 


Escape 

sequence Meaning 

Esc[2J Clear screen, place cursor in upper left corner (home position). 

Esc(K Clear from cursor to end of line. 

Esclrow;colH Position cursor. (Row is the y coordinate in the range 1-25 and col 
is the x coordinate in the range 1-80 for 80-by-25 text display 
modes.) Escape sequences terminated with the letter f instead 
of H have the same effect. 

Esc(nA Move cursor up 7 rows. 

Esc[nB Move cursor down 7 rows. 

Esc[nC Move cursor right 7 columns. 

Esc(nD Move cursor left 7 columns. 

Escls Save current cursor position. 

Esclu Restore cursor to saved position. 

Escl6n Return current cursor position on the standard input handle in the 
format Esclrow;colR. 

Esc{nm Select character attributes: 


0 = no special attributes 

1 = high intensity 

2 = low intensity 

3 = italic 

4 = underline 

5 = blink 

6 = rapid blink 

7 = reverse video ) 
8 = concealed text (no display) 
30 = foreground black 

31 = foreground red 

32 = foreground green 

33 = foreground yellow 

34 = foreground blue 

35 = foreground magenta 


a ee 


(continued) 


Figure 6-2. The ANSI escape sequences supported by the MS-DOS ANSLSYS driver. 
Programs running under MS-DOS 2.0 or later may use these functions, if ANSLSYS is 
loaded, to control the appearance of the display in a hardware-independent manner. 
The symbol Esc indicates an ASCII escape code —a character with the value 1BH. 
Note that cursor positions in ANSI escape sequences are one-based, unlike the cursor 
coordinates used by the IBM ROM BIOS, which are zero-based. Numbers embedded in 
an escape sequence must always be represented as a string of ASCII digits, not as their 
binary values. 
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Figure 6-2. continued 


Escape 
sequence Meaning 


pet’ att te tA, ccc 


36 = foreground cyan 
37 = foreground white 
40 = background black 
41 = background red 
42 = background green 
43 = background yellow 
44 = background blue 
45 = background magenta 
46 = background cyan 
47 = background white 
Escl=nh Select display mode: 
0 = 40-by-25, 16-color text (color burst off) 
1 = 40-by-25, 16-color text 
2 = 80-by-25, 16-color text (color burst off) 
3 = 80-by-25, 16-color text 
4 = 320-by-200, 4-color graphics 
5 = 320-by-200, 4-color graphics (color burst off) 
6 = 620-by-200, 2-color graphics 
14 = 640-by-200, 16-color graphics (EGA and VGA, MS-DOS 4.0) 
15 = 640-by-350, 2-color graphics (EGA and VGA, MS-DOS 4.0) 
16 = 640-by-350, 16-color graphics (EGA and VGA, MS-DOS 4.0) 
17 = 640-by-480, 2-color graphics (MCGA and VGA, MS-DOS 4.0) 
18 = 640-by-480, 16-color graphics (VGA, MS-DOS 4.0) 
19 = 320-by-200, 256-color graphics (€MCGA and VGA, MS-DOS 4.0) 
Escape sequences terminated with / instead of h have the same 


effect. 
Esc{= 7h Enable line wrap. 
Escl= 71 Disable line wrap. 
Binary Output Mode 


Under MS-DOS version 2 or later, you can substantially increase display 
speeds for well-behaved application programs without sacrificing hard- 
ware independence by selecting binary (raw) mode for the standard out- 
put. In binary mode, MS-DOS does not check between each character it 
transfers to the output device for a Ctrl-C waiting at the keyboard, nor 
does it filter the output string for certain characters such as Ctrl-Z. 


Bit 5 in the device information word associated with a device handle con- 
trols binary mode. Programs access the device information word by using 
Subfunctions 00H and 01H of the MS-DOS IOCTL function (I/O Control, 
Int 21H Function 44H). For example, the sequence on the following page 
places the standard output handle into binary mode. 
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Note that if a program changes the mode of any of the standard handles, it 
should restore those handles to ASCII (cooked) mode before it exits. 
Otherwise, subsequent application programs may behave in unexpected 
ways. For more detailed information on the IOCTL function, see Section II 
of this book, “MS-DOS Functions Reference.” 


€ ROM BIOS Display Functions 


You can somewhat improve the display performance of programs that are 
intended for use only on IBM PC-compatible machines by using the ROM 
BIOS video driver instead of the MS-DOS output functions. Accessed by 
means of Int 10H, the ROM BIOS driver supports the following functions 
for all of the currently available IBM display adapters: 


Function Action 

a ee 
Display mode control 

00H Set display mode. 

OFH Get display mode. 

Cursor control | 

01H Set cursor size. 

02H Set cursor position. 

03H Get cursor position and size. 

Writing to the display 

09H Write character and attribute at cursor. 

OAH Write character-only at cursor. 

0OEH Write character in teletype mode. 
Smee 


(continued) 
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Function Action 

Reading from the display 

08H Read character and attribute at cursor. 
Graphics support 

0CH Write pixel. 

0DH Read pixel. 

Scroll or clear display 

06H Scroll up or initialize window. 
07H Scroll down or initialize window. 
Miscellaneous 

04H Read light pen. 

05H Select display page. 

OBH Select palette/set border color. 


Additional ROM BIOS functions are available on the EGA, MCGA, VGA, 
and PCjr to support the enhanced features of these adapters, such as pro- 
grammable palettes and character sets (fonts). Some of the functions are 
valid only in certain display modes. 


Each display mode is characterized by the number of colors it can display, 
its vertical resolution, its horizontal resolution, and whether it supports 
text or graphics memory mapping. The ROM BIOS identifies it with a 
unique number. Section III of this book, “IBM ROM BIOS and Mouse 
Functions Reference,” documents all of the ROM BIOS Int 10H functions 
and display modes. 


As you can see from the preceding list, the ROM BIOS offers several desir- 
able capabilities that are not available from MS-DOS, including initializa- 
tion or scrolling of selected screen windows, modification of the cursor 
shape, and reading back the character being displayed at an arbitrary 
screen location. These functions can be used to isolate your program from 
the hardware on any IBM PC—compatible adapter. However, the ROM 
BIOS functions do not suffice for the needs of a high-performance, in- 
teractive, full-screen program such as a word processor. They do not sup- 
- port the rapid display of character strings at an arbitrary screen position, 
and they do not implement graphics operations at the level normally re- 
quired by applications (for example, bit-block transfers and rapid drawing 
of lines, circles, and filled polygons). And, of course, they are of no use 
whatsoever in non-IBM display modes such as the monochrome graphics 
mode of the Hercules Graphics Card. 
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Let’s look at a simple example of a call to the ROM BIOS video driver. The 
following sequence writes the string hello to the screen: 


(Note that the SI and DI registers are not necessarily preserved across a 
call to a ROM BIOS video function.) 


Memory-mapped Display Techniques 


Display performance is best when an application program takes over 
complete control of the video adapter and the refresh buffer. Because the 
display is memory-mapped, the speed at which characters can be put on 
the screen is limited only by the CPU’s ability to copy bytes from one loca- 
tion in memory to another. The trade-off for this performance is that such 
programs are highly sensitive to hardware compatibility and do not al- 
ways function properly on “clones” or even on new models of IBM video 
adapters. 


Text Mode 


Direct programming of the IBM PC-compatible video adapters in their 
text display modes (sometimes also called alphanumeric display modes) is 
straightforward. The character set is the same for all, and the cursor home 
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position—(x,y) = (0,0)—is defined to be the upper left corner of the 
screen (Figure 6-3). The MDA uses 4 KB of memory starting at segment 
BOOOH as a regen buffer, and the various adapters with both text and 
graphics capabilities (CGA, EGA, MCGA, and VGA) use 16 KB of memory 
starting at segment B800H. (See Figure 6-1.) In the latter case, the 16 KB is 
divided into “pages” that can be independently updated and displayed. 


(0,0) (79,0) 


(0,24) (79,24) 


Figure 6-3. Cursor addressing for 80-by-25 text display modes (IBM ROM BIOS 
modes 2, 3, and 7). 


Each character-display position is allotted 2 bytes in the regen buffer. The 
first byte (even address) contains the ASCII code of the character, which is 
translated by a special hardware character generator into a dot-matrix pat- 
tern for the screen. The second byte (odd address) is the attribute byte. 
Several bit fields in this byte control such features as blinking, intensity 
(highlighting), and reverse video, depending on the adapter type and dis- 
play mode (Figures 6-4 and 6-5). Figure 6-6 shows a hex and ASCII dump 
of part of the video map for the MDA. 


7 6 5 4 3 2 1 0 

B = Blink 

I = Intensity 
Display Background Foreground 
No display (black) 000 000 
No display (white) + 111 111 
Underline 000 001 
Normal video 000 111 
Reverse video 111 000 
“VGA only 


Figure 6-4. Attribute byte for 80-by-25 monochrome text display mode on the MDA, 
Hercules cards, EGA, and VGA (IBM ROM BIOS mode 7). 


Video Display 


97 


| 6 5 4 3 2 1 0 
Background | 1 | Foreground | 


B = Blink or background intensity (default = blink) 
I = Foreground intensity or character select (default = intensity) 


Value Color 
0 Black 
1 Blue 
2 Green 
3 Cyan 
4 Red 
5 Magenta 
6 Brown 
7 White 
8 Gray 
9 Light blue 
10 Light green 
11 Light cyan 
12 Light red 
13 Light magenta 
14 Yellow 
15 Intense white 


eee 
Figure 6-5. Attribute byte for the 40-by-25 and &0-by-25 text display modes on the 


CGA, EGA, MCGA, and VGA (IBM ROM BIOS modes 0-3). The table of color values 
assumes default palette programming and that the B or I bit controls intensity. 


Figure 6-6. Example dump of the first 160 bytes of the MDA’s regen buffer. These 
bytes correspond to the first visible line on the screen. Note that ASCII character codes 
are stored in even bytes and their respective character attributes in odd bytes; all the 
characters in this example line have the attribute normal video. 
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You can calculate the memory offset of any character on the display as the 
line number (y coordinate) times 80 characters per line times 2 bytes per 
character, plus the column number (x coordinate) times 2 bytes per char- 
acter, plus (for the text/graphics adapters) the page number times the size 
of the page (4 KB per page in 80-by-25 modes; 2 KB per page in 40-by-25 
modes). In short, the formula for the offset of the character-attribute pair 
for a given screen position (x,y) in 80-by-25 text modes is 


offset = (Cy * 5SOH + x) * 2) + (page + 1000H) 
In 40-by-25 text modes, the formula is 
offset = (Cy « 50H + x) * 2) + (page * 0800H) 


Of course, the segment register being used to address the video buffer 
must be set appropriately, depending on the type of display adapter. 


As a simple example, assume that the character to be displayed is in the 
AL register, the desired attribute byte for the character is in the AH regis- 
ter, the x coordinate (column) is in the BX register, and the y coordinate 
(row) is in the CX register. The following code stores the character and at- 
tribute byte into the MDA’s video refresh buffer at the proper location: 


More frequently, we wish to move entire strings into the refresh buffer, 
starting at a given coordinate. In the next example, assume that the DS:SI 
registers point to the source string, the ES:DI registers point to the starting 
position in the video buffer (calculated as shown in the previous ex- 
ample), the AH register contains the attribute byte to be assigned to every 
character in the string, and the CX register contains the length of the 
string. The following code moves the entire string into the refresh buffer: 
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Of course, the video drivers written for actual application programs must 
take into account many additional factors, such as checking for special 
control codes (linefeeds, carriage returns, tabs), line wrap, and scrolling. 


Programs that write characters directly to the CGA regen buffer in text 
modes must deal with an additional complicating factor—they must ex- 
amine the video controller’s status port and access the refresh buffer only 
during the horizontal retrace or vertical retrace intervals. (A retrace inter- 
val is the period when the electron beam that illuminates the screen 
phosphors is being repositioned to the start of a new scan line.) Other- 
wise, the contention for memory between the CPU and the video con- 
troller is manifest as unsightly “snow” on the display. (If you are writing 
programs for any of the other IBM PC-compatible video adapters, such as 
the MDA, EGA, MCGA, or VGA, you can ignore the retrace intervals; snow 
is not a problem with these video controllers.) 


A program can detect the occurrence of a retrace interval by monitoring 
certain bits in the video controller’s status register. For example, assume 
that the offset for the desired character position has been calculated as in 
the preceding example and placed in the BX register, the segment for the 
CGA’s refresh buffer is in the ES register, and an ASCII character code to 
be displayed is in the CL register. The following code waits for the begin- 
ning of a new horizontal retrace interval and then writes the character into 
the buffer: 
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The first wait loop “synchronizes” the code to the beginning of a horizon- 
tal retrace interval. If only the second wait loop were used (that is, if a 
character were written when a retrace interval was already in progress), 
the write would occasionally begin so close to the end of a horizontal 
retrace “window” that it would partially miss the retrace, resulting in scat- 
tered snow at the left edge of the display. Notice that the code also dis- 
ables interrupts during accesses to the video buffer, so that service of a 
hardware interrupt won’t disrupt the synchronization process. 


Because of the retrace-interval constraints just outlined, the rate at which 
you can update the CGA in text modes is severely limited when the updat- 
ing is done one character at a time. You can obtain better results by 
calculating all the relevant addresses and setting up the appropriate regis- 
ters, disabling the video controller by writing to register 3D8H, moving the 
entire string to the buffer with a REP MOVSW operation, and then 
reenabling the video controller. If the string is of reasonable length, the 
user won’t even notice a flicker in the display. Of course, this procedure 
introduces additional hardware dependence into your code because it 
requires much greater knowledge of the 6845 controller. Luckily, snow is 
not a problem in CGA graphics modes. 


Graphics Mode 


Graphics-mode memory-mapped programming for IBM PC-compatible 
adapters is considerably more complicated than text-mode programming. 
Each bit or group of bits in the regen buffer corresponds to an addressable 
point, or pixel, on the screen. The mapping of bits to pixels differs for 
each of the available graphics modes, with their differences in resolution 
and number of supported colors. The newer adapters (EGA, MCGA, and 
VGA) also use the concept of bit planes, where bits of a pixel are segre- 
gated into multiple banks of memory mapped at the same address; you 
must manipulate these bit planes by a combination of memory-mapped 
I/O and port addressing. 


IBM-video-systems graphics programming is a subject large enough for a 
book of its own, but we can use the 640-by-200, 2-color graphics display 
mode of the CGA (which is also supported by all subsequent IBM text/ 
graphics adapters) to illustrate a few of the techniques involved. This 
mode is simple to deal with because each pixel is represented by a single 
bit. The pixels are assigned (x,y) coordinates in the range (0,0) through 
(639,199), where x is the horizontal displacement, y is the vertical 
displacement, and the home position (0,0) is the upper left corner of the 
display. (See Figure 6-7.) 
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(0,0) (639,0) 


(0,199) (639,199) 


Figure 6-7. Point addressing for 640-by-200, 2-color graphics modes on the CGA, 
EGA, MCGA, and VGA (IBM ROM BIOS mode 6). 


Each successive group of 80 bytes (640 bits) represents one horizontal 
scan line. Within each byte, the bits map one-for-one onto pixels, with the 
most significant bit corresponding to the leftmost displayed pixel of a set 
of eight pixels and the least significant bit corresponding to the rightmost 
displayed pixel of the set. The memory map is set up so that all the even y 
coordinates are scanned as a set and all the odd y coordinates are scanned 
as a set; this mapping is referred to as the memory interlace. 


To find the regen buffer offset for a particular (x,y) coordinate, you would 
use the following formula: 


offset = (y AND 1) « 2000H) + (y/2 * 50H) + (x/8) 


The assembly-language implementation of this formula is as follows: 


After calculating the correct byte address, you can use the following for- 
mula to calculate the bit position for a given pixel coordinate: 


bit = 7 — (x MOD 8) 
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where bit 7 is the most significant bit and bit 0 is the least significant bit. It 
is easiest to build an 8-byte table, or array of bit masks, and use the opera- 
tion X AND 7 to extract the appropriate entry from the table: 


(X AND 7) Bit mask (X AND 7) Bit mask 
0 80H 4 08H 
1 40H 5 04H 
2 20H 6 02H 
3 10H 7 01H 


The assembly-language implementation of this second calculation is as 
follows: 


The program can then use the mask, together with the byte offset pre- 
viously calculated, to set or clear the appropriate bit in the video con- 
troller’s regen buffer. 
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MS-DOS supports printers, plotters, modems, and other hard-copy output 
or communication devices with device drivers for parallel ports and serial 
ports. Parallel ports are so named because they transfer a byte—8 bits— 
in parallel to the destination device over eight separate physical paths 
(plus additional status and handshaking signals). The serial port, on the 
other hand, communicates with the CPU with bytes but sends data to or 
receives data from its destination device serially—a bit at a time—over a 
single physical connection. 


Parallel ports are typically used for high-speed output devices, such as 
line printers, over relatively short distances (less than 50 feet). They are 
rarely used for devices that require two-way communication with the 
computer. Serial ports are used for lower-speed devices, such as modems 
and terminals, that require two-way communication (although some 
printers also have serial interfaces). A serial port can drive its device reli- 
ably over much greater distances (up to 1000 feet) over as few as three 
wires—transmit, receive, and ground. 


The most commonly used type of serial interface follows a standard called 
RS-232. This standard specifies a 25-wire interface with certain electrical 
characteristics, the use of various handshaking signals, and a standard 
DB-25 connector. Other serial-interface standards exist—for example, the 
RS-422, which is capable of considerably higher speeds than the RS-232— 
but these are rarely used in personal computers (except for the Apple 
Macintosh) at this time. 


MS-DOS has built-in device drivers for three parallel adapters, and for two 
serial adapters on the PC or PC/AT and three serial adapters on the PS/2. 
The logical names for these devices are LPT1, LPT2, LPT3, COM1, COM2, 
and COM3. The standard printer (PRN) and standard auxiliary (AUX) 
devices are normally aliased to LPT1 and COMI, but you can redirect PRN 
to one of the serial ports with the MS-DOS MODE command. 


As with keyboard and video display I/O, you can manage printer and 
serial-port I/O at several levels that offer different degrees of flexibility 
and hardware independence: 


a MS-DOS handle-oriented functions 
w MS-DOS traditional character functions 
es IBM ROM BIOS driver functions 


In the case of the serial port, direct control of the hardware by application 
programs is also common. I will discuss each of these I/O methods 
briefly, with examples, in the following pages. 
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The preferred method of printer output is to use the handle write function 
(Int 21H Function 40H) with the predefined standard printer handle (4). 
For example, you could write the string hello to the printer as follows: 


If there is no error, the function returns the carry flag cleared and the 
number of characters actually transferred to the list device in register AX. 
Under normal circumstances, this number should always be the same as 
the length requested and the carry flag indicating an error should never be 
set. However, the output will terminate early if your data contains an end- 
of-file mark (Ctrl-Z). 


You can write independently to several list devices (for example, LPT1, 
LPT2) by issuing a specific open request (Int 21H Function 3DH) for each 
device and using the handles returned to access the printers individually 
with Int 21H Function 40H. You have already seen this general approach 
in Chapters 5 and 6. 


An alternative method of printer output is to use the traditional Int 21H 
Function 05H, which transfers the character in the DL register to the 


printer. (This function is sensitive to Ctrl-C interrupts.) For example, the 


assembly-language code sequence at the top of the following page would 
write the the string Hello to the line printer. 
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"hello" 
‘$-msg 


Programs that run on IBM PC—compatible machines can obtain improved 
printer throughput by bypassing MS-DOS and calling the ROM BIOS 
printer driver directly by means of Int 17H. Section III of this book, “IBM 
ROM BIOS and Mouse Functions Reference,” documents the Int 17H func- 
tions in detail. Use of the ROM BIOS functions also allows your program 
to test whether the printer is off line or out of paper, a capability that 
MS-DOS does not offer. 


For example, the following sequence of instructions calls the ROM BIOS 
printer driver to send the string hello to the line printer: 


(continued) 
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(continued) 


Note that the printer numbers used by the ROM BIOS are zero-based, 
whereas the printer numbers in MS-DOS logical-device names are one- 
based. For example, ROM BIOS printer 0 corresponds to LPT1. 


Finally, the most hardware-dependent technique of printer output is to ac- 
cess the printer controller directly. Considering the functionality already 
provided in MS-DOS and the IBM ROM BIOS, as well as the speeds of the 
devices involved, I cannot see any justification for using direct hardware 
control in this case. The disadvantage of introducing such extreme hard- 
ware dependence for such a low-speed device would far outweigh any 
small performance gains that might be obtained. 


The Serial Port 


MS-DOS support for serial ports (often referred to as the auxiliary device 
in MS-DOS manuals) is weak compared with its keyboard, video-display, 
and printer support. This is one area where the application programmer is 
justified in making programs hardware dependent to extract adequate 
performance. 


Programs that restrict themselves to MS-DOS functions to ensure por- 
tability can use the handle read and write functions (nt 21H Functions 
3FH and 40H), with the predefined standard auxiliary handle (3) to access 
the serial port. For example, the following code writes the string hello to 
the serial port that is currently defined as the AUX device: 


(continued) 
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The standard auxiliary handle gives access to only the first serial port 
(COM1). If you want to read or write COM2 and COM3 using the handle 
calls, you must issue an open request (Int 21H Function 3DH) for the 
desired serial port and use the handle returned by that function with Int 
21H Functions 3FH and 40H. 


Some versions of MS-DOS have a bug in character-device handling that 
manifests itself as follows: If you issue a read request with Int 21H Func- 
tion 3FH for the exact number of characters that are waiting in the driver's 
buffer, the length returned in the AX register is the number of characters 
transferred minus one. You can circumvent this problem by always re- 
questing more characters than you expect to receive or by placing the 
device handle into binary mode using Int 21H Function 44H. 


MS-DOS also supports two traditional functions for serial-port I/O. Int 21H 
Function 03H inputs a character from COM1 and returns it in the AL regis- 
ter; Int 21H Function 04H transmits the character in the DL register to 
COM1. Like the other traditional calls, these two are direct descendants of 
the CP/M auxiliary-device functions. 


For example, the following code sends the string hello to COM1 using the 
traditional Int 21H Function 04H: 


(continued) 
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(continued) 


MS-DOS translates the traditional auxiliary-device functions into calls on 
the same device driver used by the handle calls. Therefore, it is generally 
preferable to use the handle functions in the first place, because they 
allow very long strings to be read or written in one operation, they give 
access to serial ports other than COMI, and they are symmetrical with the 
handle video-display, keyboard, printer, and file I/O methods described 
elsewhere in this book. 


Although the handle or traditional serial-port functions allow you to write 
programs that are portable to any machine running MS-DOS, they have a 
number of disadvantages: 


The built-in MS-DOS serial-port driver is slow and is not interrupt 
driven. 


MS-DOS serial-port I/O is not buffered. 


= Determining the status of the auxiliary device requires a separate call 
to the IOCTL function (Int 21H Function 44H)—f you request input 
and no characters are ready, your program will simply hang. 


MS-DOS offers no standardized function to configure the serial port 
from within a program. 


For programs that are going to run on the IBM PC or compatibles, a more 
flexible technique for serial-port I/O is to call the IBM ROM BIOS serial- 
port driver by means of Int 14H. You can use this driver to initialize the 
serial port to a desired configuration and baud rate, examine the status of 
the controller, and read or write characters. Section III of this book, “IBM 
ROM BIOS and Mouse Functions Reference,” documents the functions 
available from the ROM BIOS serial-port driver. 
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For example, the following sequence sends the character X to the first 
serial port (COMI): 


112 


As with the ROM BIOS printer driver, the serial-port numbers used by the 
ROM BIOS are zero-based, whereas the serial-port numbers in MS-DOS 
logical-device names are one-based. In this example, serial port 0 corre- 
sponds to COM1. 


Unfortunately, like the MS-DOS auxiliary-device driver, the ROM BIOS 
serial-port driver is not interrupt driven. Although it will support higher 
transfer speeds than the MS-DOS functions, at rates greater than 2400 
baud it may still lose characters. Consequently, most programmers writing 
high-performance applications that use a serial port (such as telecom- 
munications programs) take complete control of the serial-port controller 
and provide their own interrupt driver. The built-in functions provided by 
MS-DOS, and by the ROM BIOS in the case of the IBM PC, are simply not 
adequate. 


Writing such programs requires a good understanding of the hardware. In 
the case of the IBM PC, the chips to study are the INS8250 Asynchronous 
Communications Controller and the Intel 8259A Programmable Interrupt 
Controller. The IBM technical reference documentation for these chips is 
a bit disorganized, but most of the necessary information is there if you 
look for it. 
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The TALK Program 


The simple terminal-emulator program TALK.ASM (Figure 7-1) is an ex- 
ample of a useful program that performs screen, keyboard, and serial-port 
I/O. This program recapitulates all of the topics discussed in Chapters 5 
through 7. ZALK uses the IBM PC’s ROM BIOS video driver to put charac- 
ters on the screen, to clear the display, and to position the cursor; it uses 
the MS-DOS character-input calls to read the keyboard; and it contains its 
own interrupt driver for the serial-port controller. 


standar 4 tnput handle ce os ee 


PAS ASCIT’ WY nef eed : 
ATL backspace 


(continued) 


Figure 7-1. TALK.ASM: A simple terminal-emulator program for IBM PC-—compatible 
computers. This program demonstrates use of the MS-DOS and ROM BIOS video and 
keyboard functions and direct control of the serial-communications adapter. 
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Figure 7-1. continued 
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Figure 7-1. continued 
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proc 
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Figure 7-1. continued 
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Figure 7-1. continued 


The TALK program illustrates the methods that an application should use 
to take over and service interrupts from the serial port without running 
afoul of MS-DOS conventions. | 


The program begins with some equates and conditional assembly state- 
ments that configure the program for half- or full-duplex and for the 
desired serial port (COM1 or COM2). At entry from MS-DOS, the main rou- 
tine of the program—the procedure named talk—checks the status of 
the serial port, initializes the display, and calls the asc_enb routine to take 
over the serial-port interrupt vector and enable interrupts. The talk pro- 
cedure then enters a loop that reads the keyboard and sends the charac- 
ters out the serial port and then reads the serial port and puts the 
characters on the display—in other words, it causes the PC to emulate a 
simple CRT terminal. 


The TALK program intercepts and handles control codes (carriage return, 
linefeed, and so forth) appropriately. It detects escape sequences and 
handles them as a subset of the Televideo 950 terminal capabilities. (You 
can easily modify the program to emulate any other cursor-addressable 
terminal.) When one of the PC’s special function keys is pressed, the 
program disables serial-port interrupts, releases the serial-port interrupt 
vector, and exits back to MS-DOS. 


There are several TALK program procedures that are worth your attention 
because they can easily be incorporated into other programs. These are 
listed in the table on the following page. 
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Nene pee 


Procedure 


asc_enb 


asc._dsb 


asc_int 
com_ stat 
com_in 


com_out 
cls 
clreol 


home 
gotoxy 
Setxy 
pc_out 
pc_stat 
pc_in 


Action 


Takes over the serial-port interrupt vector and enables interrupts 
by writing to the modem-control register of the INS8250 and 
the interrupt-mask register of the 8259A. 

Restores the original state of the serial-port interrupt vector and 
disables interrupts by writing to the interrupt-mask register of 
the 8259A. 

Services serial-port interrupts, placing received characters into a 
ring buffer. 

Tests whether characters from the serial port are waiting in the 
ring buffer. 

Removes characters from the interrupt handler’s ring buffer and 
increments the buffer pointers appropriately. 

Sends one character to the serial port. 

Calls the ROM BIOS video driver to clear the screen. 

Calls the ROM BIOS video driver to clear from the current cursor 
position to the end of the line. 

Places the cursor in the upper left corner of the screen. 

Positions the cursor at the desired position on the display. 

Obtains the current cursor position. 

Sends one character to the PC’s display. 

Gets status for the PC’s keyboard. 

Returns a character from the PC’s keyboard. 


_——————-_-_-_-_-_-_— ee 
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The dual heritage of MS-DOS—CP/M and UNIX/XENIX—is perhaps 
most clearly demonstrated in its file-management services. In general, 
MS-DOS provides at least two distinct operating-system calls for each ma- 
jor file or record operation. This chapter breaks this overlapping battery 
of functions into two groups and explains the usage, advantages, and 
disadvantages of each. 


I will refer to the set of file and record functions that are compatible with 
CP/M as FCB functions. These functions rely on a data structure called a 
file control block (hence, FCB) to maintain certain bookkeeping informa- 
tion about open files. This structure resides in the application program’s 
memory space. The FCB functions allow the programmer to create, open, 
close, and delete files and to read or write records of any size at any record 
position within such files. These functions do not support the hierarchical 
(treelike) file structure that was first introduced in MS-DOS version 2.0, sO 
they can be used only to access files in the current subdirectory for a given 
disk drive. 


I will refer to the set of file and record functions that provide compatibility 
with UNIX/XENIX as the handle functions. These functions allow the 
programmer to open or create files by passing MS-DOS a null-terminated 
string that describes the file’s location in the hierarchical file structure (the 
drive and path), the file’s name, and its extension. If the open or create 
Operation is successful, MS-DOS returns a 16-bit token, or handle, that is 
saved by the application program and used to specify the file in subse- 
quent operations. 


When you use the handle functions, the operating system maintains the 
data structures that contain bookkeeping information about the file inside 
its own memory space, and these structures are not accessible to the ap- 
plication program. The handle functions fully support the hierarchical file 
structure, allowing the programmer to create, open, close, and delete files 
in any subdirectory on any disk drive and to read or write records of any 
size at any byte offset within such files. 


Although we are discussing the FCB functions first in this chapter for 
historical reasons, new MS-DOS applications should always be written 
using the more powerful handle functions. Use of the FCB functions in 
new programs should be avoided, unless compatibility with MS-DOS 
version 1.0 is needed. 
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Using the FCB Functions 


Understanding the structure of the file control block is the key to success 
with the FCB family of file and record functions. An FCB is a 37-byte data 
structure allocated within the application program’s memory space; it is 
divided into many fields (Figure 8-1). Typically, the program initializes an 
FCB with a drive code, a filename, and an extension (conveniently accom- 
plished with the parse-filename service, Int 21H Function 29H) and then 
passes the address of the FCB to MS-DOS to open or create the file. If the 
file is successfully opened or created, MS-DOS fills in certain fields of the 
FCB with information from the file’s entry in the disk directory. This infor- 
mation includes the file’s exact size in bytes and the date and time the file 
was created or last updated. MS-DOS also places certain other information 
within a reserved area of the FCB; however, this area is used by the 
operating system for its own purposes and varies among different versions 
of MS-DOS. Application programs should never modify the reserved area. 


For compatibility with CP/M, MS-DOS automatically sets the record-size 
field of the FCB to 128 bytes. If the program does not want to use this 
default record size, it must place the desired size Gin bytes) into the record- 
size field after the open or create operation. Subsequently, when the pro- 
gram needs to read or write records from the file, it must pass the address 
of the FCB to MS-DOS; MS-DOS, in turn, keeps the FCB updated with in- 
formation about the current position of the file pointer and the size of the 
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Figure 8-1. Normal file control block. Total length is 37 bytes (25H bytes). See notes 
on pages 133-34. 
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file. Data is always read to or written from the current disk transfer area 
(DTA), whose address is set with Int 21H Function 1AH. If the application 
program wants to perform random record access, it must set the record 
number into the FCB before issuing each function call; when sequential 
record access is being used, MS-DOS maintains the FCB and no special in- 
tervention is needed from the application. 


In general, MS-DOS functions that use FCBs accept the full address of the 
FCB in the DS:DX register and pass back a return code in the AL register 
(Figure 8-2). For file-management calls (open, close, create, and delete), 
this return code is zero if the function was successful and OF FH (255) if 
the function failed. For the FCB-type record read and write functions, the 
success code returned in the AL register is again zero, but there are sev- 
eral failure codes. Under MS-DOS version 3.0 or later, more detailed error 
reporting can be obtained by calling Int 21H Function 59H (Get Extended 
Error Information) after a failed FCB function call. 


When a program is loaded under MS-DOS, the operating system sets up 
two FCBs in the program segment prefix, at offsets 005CH and 006CH. 
These are often referred to as the default FCBs, and they are included to 
provide upward compatibility from CP/M. MS-DOS parses the first two 
parameters in the command line that invokes the program (excluding any 
redirection directives) into the default FCBs, under the assumption that 
they may be file specifications. The application must determine whether 
they really are filenames or not. In addition, because the default FCBs 
overlap and are not in a particularly convenient location (especially for 
-EXE programs), they usually must be copied elsewhere in order to be 
used safely. (See Chapter 3.) 


Figure 8-2. A typical FCB file operation. This sequence of code attempts to open the 
file whose name was previously parsed into the FCB named my_fcb. 
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Note that the structures of FCBs under CP/M and MS-DOS are not identi- 
cal. However, the differences lie chiefly in the reserved areas of the FCBs 
(which should not be manipulated by application programs in any case), 
so well-behaved CP/M applications should be relatively easy to port into 
MS-DOS. It seems, however, that few such applications exist. Many of the 
tricks that were played by clever CP/M programmers to increase perfor- 
mance or circumvent the limitations of that operating system can cause 
severe problems under MS-DOS, particularly in networking environ- 
ments. At any rate, much better performance can be achieved by thor- 
oughly rewriting the CP/M applications to take advantage of the superior 
capabilities of MS-DOS. 


You can use a special FCB variant called an extended file control block to 
create or access files with special attributes (such as hidden or read-only 
files), volume labels, and subdirectories. An extended FCB has a 7-byte 
header followed by the 37-byte structure of a normal FCB (Figure 8-3). 
The first byte contains OFFH, which could never be a legal drive code and 
thus indicates to MS-DOS that an extended FCB is being used. The next 5 
bytes are reserved and are unused in current versions of MS-DOS. The 
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Figure 8-3. Extended file control block. Total length is 44 bytes (2CH bytes). See notes 
on pages 133 34. 
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seventh byte contains the attribute of the special file type that is being ac- 
cessed. (Attribute bytes are discussed in more detail in Chapter 9.) Any 
MS-DOS function that uses a normal FCB can also use an extended FCB. 


The FCB file- and record-management functions may be gathered into the 
following broad classifications: 


es 


Function Action 

Common FCB file operations 

OFH Open file. 

10H Close file. 

16H Create file. 

Common FCB record operations 

14H Perform sequential read. 
15H Perform sequential write. 
21H Perform random read. 

22H Perform random write. 

27H Perform random block read. 
28H Perform random block write. 


Other vital FCB operations 
1AH Set disk transfer address. 
29H Parse filename. 


Less commonly used FCB file operations 


13H Delete file. 

17H Rename file. 

Less commonly used FCB record operations 
23H Obtain file size. 

24H Set relative-record number. 


ee 
Several of these functions have special properties. For example, Int 21H 
Functions 27H (Random Block Read) and 28H (Random Block Write) 
allow reading and writing of multiple records of any size and also update 
the random-record field automatically (unlike Int 21H Functions 21H and 
22H). Int 21H Function 28H can truncate a file to any desired size, and Int 
21H Function 17H used with an extended FCB can alter a volume label or 
rename a subdirectory. 


Section II of this book, “MS-DOS Functions Reference,” gives detailed 
specifications for each of the FCB file and record functions, along with 
assembly-language examples. It is also instructive to compare the preced- 
ing groups with the corresponding groups of handle-type functions listed 
on pages 140-41. 
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Notes for Figures 8-1 and 8-3. continued 


FCB File-Access Skeleton 


The following is a typical program sequence to access a file using the FCB, 
or traditional, functions (Figure 8-4): 
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1. 
2. 


Zero out the prospective FCB. 


Obtain the filename from the user, from the default FCBs, or from the 
command tail in the PSP. 


. If the filename was not obtained from one of the default FCBs, parse 


the filename into the new FCB using Int 21H Function 29H. 


. Open the file nt 21H Function OFH) or, if writing new data only, 


create the file or truncate any existing file of the same name to zero 
length (Int 21H Function 16H). 


. Set the record-size field in the FCB, unless you are using the default 


record size. Recall that it is important to do this after a successful open 
or create operation. (See Figure 8-5.) 


. Set the relative-record field in the FCB if you are performing random 


record I/O. 


Set the disk transfer area address using Int 21H Function 1AH, unless 
the buffer address has not been changed since the last call to this func- 
tion. If the application never performs a set DTA, the DTA address 
defaults to offset 0080H in the PSP. 


. Request the needed read- or write-record operation (Int 21H Function 


14H—Sequential Read, 15H-Sequential Write, 21H-Random Read, 22H— 
Random Write, 27H-Random Block Read, 283H-Random Block Write). 


(continued) 
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(continued) 


Figure 8-4. Skeleton of an assembly-language program that performs file and record 


V/O using the FCB family of functions. 
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Figure 8-4. continued 
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Figure 8-5. A typical file control block before and after a successful open call 
(Int 21H Function OFH). 
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9. If the program is not finished processing the file, go to step 6; other- 
wise, close the file (Int 21H Function 10H). If the file was used for 
reading only, you can skip the close operation under early versions of 
MS-DOS. However, this shortcut can cause problems under MS-DOS 
versions 3.0 and later, especially when the files are being accessed 
across a network. 


Points to Remember 


Here is a summary of the pros and cons of using the FCB-related file and 
record functions in your programs. 


Advantages: 


Under MS-DOS versions 1 and 2, the number of files that can be open 
concurrently when using FCBs is unlimited. (This is not true under MS- 
DOS versions 3.0 and later, especially if networking software is 
running.) 


File-access methods using FCBs are familiar to programmers with a 
CP/M background, and well-behaved CP/M applications require little 
change in logical flow to run under MS-DOS. 


« MS-DOS supplies the size, time, and date for a file to its FCB after the 
file is opened. The calling program can inspect this information. 


Disadvantages: 
# FCBs take up room in the application program’s memory space. 


® FCBs offer no support for the hierarchical file structure (no access to 
files outside the current directory). 


FCBs provide no support for file locking/ sharing or record locking in 
networking environments. 


In addition to the read or write call itself, file reads or writes using 
FCBs require manipulation of the FCB to set record size and record 
number, plus a previous call to a separate MS-DOS function to set the 
DTA address. 


# Random record I/O using FCBs for a file containing variable-length 
records is very clumsy and inconvenient. 


You must use extended FCBs, which are incompatible with CP/M any- 
way, to access or create files with special attributes such as hidden, 
read-only, or system. 
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The FCB file functions have poor error reporting. This situation has 
been improved somewhat in MS-DOS version 3 because a program can 
call the added Int 21H Function 59H (Get Extended Error Information) 
after a failed FCB function to obtain additional information. 


# Microsoft discourages use of FCBs. FCBs will make your program more 
difficult to port to MS OS/2 later because MS OS/2 does not support 
FCBs in protected mode at all. 


Using the Handle Functions 


The handle file- and record-management functions access files in a 
fashion similar to that used under the UNIX/XENIX operating system. 
Files are designated by an ASCIIZ string (an ASCII character string termi- 
nated by a null, or zero, byte) that can contain a drive designator, path, 
filename, and extension. For example, the file specification 


C: \SYSTEM\COMMAND . COM 
would appear in memory as the following sequence of bytes: 
43 3A 5C 53 59 53 54 45 4D SC 43 4F 4D 4D 41 4E 44 2E 43 4F 4D 00 


When a program wishes to open or create a file, it passes the address of 
the ASCIIZ string specifying the file to MS-DOS in the DS:DX registers 
(Figure 8-6). If the operation is successful, MS-DOS returns a 16-bit handle 
to the program in the AX register. The program must save this handle for 
further reference. 


Figure 8-6. A typical handle file operation. This sequence of code attempts to open 
the file designated in the ASCIIZ string whose address is passed to MS-DOS in the 
DS:DX registers. 
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When the program requests subsequent operations on the file, it usually 
places the handle in the BX register before the call to MS-DOS. All the 
handle functions return with the CPU’s carry flag cleared if the operation 
was successful, or set if the operation failed; in the latter case, the AX 
register contains a code describing the failure. 


MS-DOS restricts the number of handles that can be active at any one 
time—that is, the number of files and devices that can be open concur- 
rently when using the handle family of functions—in two different ways: 


= The maximum number of concurrently open files in the system, for all 
active processes combined, is specified by the entry 


FILES=nn 


in the CONFIG.SYS file. This entry determines the number of entries 
to be allocated in the system file table; under MS-DOS version 3, the 
default value is 8 and the maximum is 255. After MS-DOS is booted 
and running, you cannot expand this table to increase the total number 
of files that can be open. You must use an editor to modify the CON- 
FIG.SYS file and then restart the system. 


=" The maximum number of concurrently open files for a single process 
is 20, assuming that sufficient entries are also available in the system 
file table. When a program is loaded, MS-DOS preassigns 5 of its po- 
tential 20 handles to the standard devices. Each time the process issues 
an open or create call, MS-DOS assigns a handle from the process’s pri- 
vate allocation of 20, until all the handles are used up or the system file 
table is full. In MS-DOS versions 3.3 and later, you can expand the per- 
process limit of 20 handles with a call to Int 21H Function 67H Get 
Handle Count). 


The handle file- and record-management calls may be gathered into the 
following broad classifications for study: 


Function Action 

Common handle file operations 

3CH Create file (requires ASCIIZ string). 

3DH Open file (requires ASCIIZ string). 

3EH Close file. 

‘Common handle record operations 

42H Set file pointer (also used to find file size). 
3FH Read file. 

40H Write file. 
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Function Action 

Less commonly used handle operations 

41H Delete file. 

43H Get or modify file attributes. 

44H IOCTL (//O Control). 

45H Duplicate handle. 

46H Redirect handle. 

56H Rename file. 

57H Get or set file date and time. 

5AH Create temporary file (versions 3.0 and later). 
5BH Create file (fails if file already exists; versions 3.0 and later). 
5CH Lock or unlock file region (versions 3.0 and later). 
67H Set handle count (versions 3.3 and later). 

68H Commit file (versions 3.3 and later). 

6CH Extended open file (version 4). 


Compare the groups of handle-type functions in the preceding table with 
the groups of FCB functions outlined earlier, noting the degree of func- 
tional overlap. Section II of this book, “MS-DOS Functions Reference,” 
gives detailed specifications for each of the handle functions, along with 
assembly-language examples. 


Handle File-Access Skeleton 


The following is a typical program sequence to access a file using the 
handle family of functions (Figure 8-7): 


1. Get the filename from the user by means of the buffered input service 
(int 21H Function 0AH) or from the command tail supplied by MS- 
DOS in the PSP. 


2. Put a zero at the end of the file specification in order to create an 
ASCIIZ string. 


3. Open the file using Int 21H Function 3DH and mode 2 (read/write 
access), or create the file using Int 21H Function 3CH. (Be sure to set 
the CX register to zero, so that you don’t accidentally make a file with 
special attributes.) Save the handle that is returned. 


4. Set the file pointer using Int 21H Function 42H. You may set the file- 
pointer position relative to one of three different locations: the start of 
the file, the current pointer position, or the end of the file. If you are 
performing sequential record I/O, you can usually skip this step 
because MS-DOS will maintain the file pointer for you automatically. 
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5. Read from the file (nt 21H Function 3FH) or write to the file (Int 21H 
Function 40H). Both of these functions require that the BX register 
contain the file’s handle, the CX register contain the length of the 
record, and the DS:DX registers point to the data being transferred. 
Both return the actual number of bytes transferred in the AX register. 


In a read operation, if the number of bytes read is less than the number 
requested, the end of the file has been reached. In a write operation, if 
the number of bytes written is less than the number requested, the disk 
containing the file is full. Neither of these conditions is returned as an 
error code; that is, the carry flag is not set. 


6. If the program is not finished processing the file, go to step 4; other- 
wise, close the file (Int 21H Function 3EH). Any normal exit from the 
program will also close all active handles. 


(continued) 


Figure 8-7. Skeleton of an assembly-language program that performs sequential 
processing on an input file and writes the results to an output file using the handle file 
and record functions. This code assumes that the DS and ES registers have already 
been set to point to the segment containing the buffers and filenames. 
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Figure 8-7. continued 
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Points to Remember 


Here is a summary of the pros and cons of using the handle file and record 
operations in your program. Compare this list with the one given earlier 
in the chapter for the FCB family of functions. 


Advantages: 


=" The handle calls provide direct support for I/O redirection and pipes 
with the standard input and output devices in a manner functionally 
similar to that used by UNIX/XENIX. 


=" The handle functions provide direct support for directories (the 
hierarchical file structure) and special file attributes. 


= The handle calls support file sharing/locking and record locking in 
networking environments. 


= Using the handle functions, the programmer can open channels to 
character devices and treat them as files. 


=" The handle calls make the use of random record access extremely 
easy. The current file pointer can be moved to any byte offset relative 
to the start of the file, the end of the file, or the current pointer posi- 
tion. Records of any length, up to an entire segment (65,535 bytes), can 
be read to any memory address in one operation. 


=" The handle functions have relatively good error reporting in MS-DOS 
version 2, and error reporting has been enhanced even further in MS- 
DOS versions 3.0 and later. 


" Microsoft strongly encourages use of the handle family of functions in 
order to provide upward compatibility with MS OS/2. 
Disadvantages: 


= There is a limit per program of 20 concurrently open files and devices 
using handles in MS-DOS versions 2.0 through 3.2. 


=" Minor gaps still exist in the implementation of the handle functions. 
For example, you must still use extended FCBs to change volume 
labels and to access the contents of the special files that implement 
directories. 
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MS-DOS Error Codes 


When one of the handle file functions fails with the carry flag set, or when 
a program calls Int 21H Function 59H (Get Extended Error Information) 
following a failed FCB function or other system service, one of the fol- 
lowing error codes may be returned: 


Value 


MS-DOS version 2 error codes 


Meaning 


01H Function number invalid 

02H File not found 

03H Path not found 

04H Too many open files 

05H Access denied 

06H Handle invalid 

07H Memory control blocks destroyed 
08H Insufficient memory 

09H Memory block address invalid 
OAH (10) Environment invalid 

OBH (11) Format invalid 

OCH (12) Access code invalid 

ODH (13) Data invalid 

OEH (14) Unknown unit 

OFH (15) Disk drive invalid 

10H (16) Attempted to remove current directory 
11H (7) Not same device 

12H (18) No more files 


Mappings to critical-error codes 


13H (19) Write-protected disk 

14H (20) Unknown unit 

15H (21) Drive not ready 

16H (22) Unknown command 

17H (23) Data error (CRC) 

18H (24) Bad request-structure length 
19H (25) Seek error 

1AH (26) Unknown media type 

1BH (27) Sector not found 

1CH (28) Printer out of paper 

1DH (29) Write fault 

1EH (30) Read fault 

1FH (1) General failure 

MS-DOS version 3 and later extended error codes 
20H (32) Sharing violation 

21H (33) File-lock violation 

22H (34) Disk change invalid 


(continued) 
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continued 


Value Meaning 

MS-DOS version 3 and later extended error codes, continued 
23H (35) © FCB unavailable 

24H (36) Sharing buffer exceeded 


25H-—31H (37-49) Reserved 
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32H (50) Unsupported network request 
33H (51) Remote machine not listening 
34H (52) Duplicate name on network 

35H (53) Network name not found 

36H (54) Network busy 

37H (55) Device no longer exists on network 
38H (56) NetBIOS command limit exceeded 
39H (57) Error in network adapter hardware 
3AH (58) Incorrect response from network 
3BH (59) Unexpected network error 

3CH (60) Remote adapter incompatible 
3DH (61) Print queue full 

3EH (62) Not enough room for print file 
3FH (63) Print file was deleted 

40H (64) Network name deleted 

41H (65) Network access denied 

42H (66) Incorrect network device type 
43H (67) Network name not found 

44H (68) Network name limit exceeded 
45H (69) NetBIOS session limit exceeded 
46H (70) Temporary pause 

47H (71) Network request not accepted 
48H (72) _ Print or disk redirection paused 
49H-4FH (73-79) Reserved 

50H (80) File already exists 

51H (81) Reserved 

52H (82) Cannot make directory 

53H (83) Fail on Int 24H (critical error) 
54H (84) Too many redirections 

55H (85) Duplicate redirection 

56H (86) Invalid password 

57H (87) Invalid parameter 

58H (88) Net write fault 


ee a 
Under MS-DOS versions 3.0 and later, you can also use Int 21H Function 
59H to obtain other information about the error, such as the error locus 
and the recommended recovery action. 
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Critical-Error Handlers 

In Chapter 5, we discussed how an application program can take over the 
Ctrl-C handler vector (Int 23H) and replace the MS-DOS default handler, to 
avoid losing control of the computer when the user enters a Ctrl-C or Ctrl- 
Break at the keyboard. Similarly, MS-DOS provides a critical-error-handler 
vector (Int 24H) that defines the routine to be called when unrecoverable 
hardware faults occur. The default MS-DOS critical-error handler is the 
routine that displays a message describing the error type and the cue 


Abort, Retry, Ignore? 


This message appears after such actions as the following: 


s Attempting to open a file on a disk drive that doesn’t contain a floppy 
disk or whose door isn’t closed 


a Trying to read a disk sector that contains a CRC error 
= Trying to print when the printer is off line 


The unpleasant thing about MS-DOS’s default critical-error handler is, of 
course, that if the user enters an A for Abort, the application that is cur- 
rently executing is terminated abruptly and never has a chance to clean 
up and make a graceful exit. Intermediate files may be left on the disk, 
files that have been extended using FCBs are not properly closed so that 
the directory is updated, interrupt vectors may be left pointing into the 
transient program area, and so forth. 


To write a truly bombproof MS-DOS application, you must take over the 
critical-error-handler vector and point it to your own routine, so that your 
program intercepts all catastrophic hardware errors and handles them ap- 
propriately. You can use MS-DOS Int 21H Function 25H to alter the Int 24H 
vector in a well-behaved manner. When your application exits, MS-DOS 
will automatically restore the previous contents of the Int 24H vector from 
information saved in the program segment prefix. 


MS-DOS calls the critical-error handler for two general classes of errors— 
disk-related and non-disk-related—and passes different information to 
the handler in the registers for each of these classes. 


For disk-related errors, MS-DOS sets the registers as shown on the follow- 
ing page. (Bits 3-5 of the AH register are relevant only in MS-DOS 
versions 3.1 and later.) 
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Register Bit(s) Significance 


AH 7 0, to signify disk error 

6 Reserved 

> 0 = ignore response not allowed 
1 = ignore response allowed 

4 0 = retry response not allowed 
1 = retry response allowed 

3 0 = fail response not allowed 
1 = fail response allowed 

1-2 Area where disk error occurred 


00 = MS-DOS area 

01 = file allocation table 
10 = root directory 

11 = files area 


0 0 = read operation 
1 = write operation 
AL 0-7 Drive code (0 = A, 1 = B, and so forth) 
DI 0-7 Driver error code 
8-15 Not used 
BP:SI Segment:offset of device-driver header 


For non-disk-related errors, the interrupt was generated either as the 
result of a character-device error or because a corrupted memory image 
of the file allocation table was detected. In this case, MS-DOS sets the 
registers as follows: 


Register Bit(s) Significance 
AH 7 1, to signify a non-disk error 
DI 0-7 Driver error code 
8-15 Not used 
BP:SI Segment:offset of device-driver header 


To determine whether the critical error was caused by a character device, 
use the address in the BP:SI registers to examine the device attribute word 
at offset 0004H in the presumed device-driver header. If bit 15 is set, then 
the error was indeed caused by a character device, and the program can 
inspect the name field of the driver’s header to determine the device. 


At entry to a critical-error handler, MS-DOS has already disabled interrupts 
and set up the stack as shown in Figure 8-8. A critical-error handler cannot 
use any MS-DOS services except Int 21H Functions 01H through OCH (Tra- 
ditional Character I/O), Int 21H Function 30H (Get MS-DOS Version), and 
Int 21H Function 59H (Get Extended Error Information). These functions 
use a special stack so that the context of the original function (which gen- 
erated the critical error) will not be lost. 
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Figure 8-8. The stack at entry to a critical-error handler. 


The critical-error handler should return to MS-DOS by executing an IRET, 
passing one of the following action codes in the AL register: 


Code Meaning 


es CA et, a a 

0 Ignore the error (MS-DOS acts as though the original function call had 
succeeded). 

1 Retry the operation. 

2 Terminate the process that encountered the error. 

3 Fail the function (an error code is returned to the requesting process). 


Versions 3.1 and later only. 


The critical-error handler should preserve all other registers and must not 
modify the device-driver header pointed to by BP:SI. A skeleton example 
of a critical-error handler is shown in Figure 8-9. 
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Figure 8-9.A skeleton example of a replacement critical-error handler. (continued) 
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Figure 8-9. continued 
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Example Programs: DUMP.ASM and DUMP.C 


The programs DUMP.ASM (Figure 8-10) and DUMP.C (Figure 8-11) are 
parallel examples of the use of the handle file and record functions. The 


assembly-language version, in particular, illustrates features of a well- 
behaved MS-DOS utility: 


# The program checks the version of MS-DOS to ensure that all the func- 
tions it is going to use are really available. 
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The program parses the drive, path, and filename from the command 
tail in the program segment prefix. 


w The program uses buffered I/O for speed. 
# The program sends error messages to the standard error device. 


a The program sends normal program output to the standard output 
device, so that the dump output appears by default on the system con- 
sole but can be redirected to other character devices (such as the line 
printer) or to a file. 


The same features are incorporated into the C version of the program, but 
some of them are taken care of behind the scenes by the C runtime 
library. 


Figure 8-10. The assembly-language version: DUMP.ASM. (continued) 
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Figure 8-10. continued 
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(continued) 
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Figure 8-10. continued 
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Figure 8-10. continued 
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Figure 8-10. continued 
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Figure 8-10. continued 
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Figure 8-11. The C version: DUMP.C. (continued) 


FileManagement 161 


Figure 8-11. continued 
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Figure 8-11. continued 


The assembly-language version of the DUMP program contains a number 
of subroutines that you may find useful in your own programming efforts. 
These include the following: 


ee  ___._ 


Subroutine Action 


argc Returns the number of command-line arguments. 

argv Returns the address and length of a particular command-line 
argument. 

w2a Converts a binary word (16 bits) into hex ASCII for output. 

b2a Converts a binary byte (8 bits) into hex ASCII for output. 

ascit Converts 4 bits into a single hex ASCII character. 


a SS 


It is interesting to compare these two equivalent programs. The C pro- 
gram contains only 77 lines, whereas the assembly-language program has 
436 lines. Clearly, the C source code is less complex and easier to main- 
tain. On the other hand, if size and efficiency are important, the 
DUMPEXE file generated by the C compiler is 8563 bytes, whereas the 
assembly-language DUMP.EXE file is only 1294 bytes and runs twice as 
fast as the C program. 
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Chapter 9 
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Each file in an MS-DOS system is uniquely identified by its name and its 
location. The location, in turn, has two components: the logical drive that 
contains the file and the directory on that drive where the filename can 
be found. 


Logical drives are specified by a single letter followed by a colon (for ex- 
ample, A:). The number of logical drives in a system is not necessarily the 
same as the number of physical drives; for example, it is common for large 
fixed-disk drives to be divided into two or more logical drives. The key 
aspect of a logical drive is that it contains a self-sufficient Jile system; that 
is, it contains one or more directories, zero or more complete files, and all 
the information needed to locate the files and directories and to determine 
which disk space is free and which is already in use. 


Directories are simply lists or catalogs. Each entry in a directory consists of 
the name, size, starting location, attributes, and last modification date and 
time of a file or another directory that the disk contains. The detailed in- 
formation about the location of every block of data assigned to a file or 
directory is in a separate control area on the disk called the file allocation 
table (FAT). (See Chapter 10 for a detailed discussion of the internal format 
of directories and the FAT.) 


Every disk potentially has two distinct kinds of directories: the root direc- 
tory and all other directories. The root directory is always present and has 
a maximum number of entries, determined when the disk is formatted; 
this number cannot be changed. The subdirectories of the root directory, 
which may or may not be present on a given disk, can be nested to any 
level and can grow to any size (Figure 9-1). This is the hierarchical, or 
tree, directory structure referred to in earlier chapters. Every directory has 
a name, except for the root directory, which is designated by a single 
backslash (\) character. 


MS-DOS keeps track of a “current drive” for the system and uses this drive 
when a file specification does not include an explicit drive code. Similarly, 
MS-DOS maintains a “current directory” for each logical drive. You can 
select any particular directory on a drive by naming in order—either from 
the root directory or relative to the current directory—the directories that 
lead to its location in the tree structure. Such a list of directories, separated 
by backslash delimiters, is called a path. When a complete path from the 
root directory is prefixed by a logical drive code and followed by a file- 
name and extension, the resulting string is a fully qualified filename and 
unambiguously specifies a file. 
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File A 


: SEU ee gee ae 


‘ 
: Directory 


. Drive 
: pau 


Root directory 
(volume label) 


Figure 9-1. An MS-DOS file-system structure. 


Drive and Directory Control 


You can examine, select, create, and delete disk directories interactively 
with the DIR, CHDIR (CD), MKDIR (MD), and RMDIR (RD) commands. 
You can select a new current drive by entering the letter of the desired 
drive, followed by a colon. MS-DOS provides the following Int 21H func- 
tions to give application programs similar control over drives and 


directories: 


se 


Function 


OEH 
19H 
39H 
3AH 
3BH 
47H 


Action 


Select current drive. 
Get current drive. - 
Create directory. 
Remove directory. 
Select current directory. 
Get current directory. 


a 
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The two functions that deal with disk drives accept or return a binary 
drive code—0 represents drive A, 1 represents drive B, and so on. This 
differs from most other MS-DOS functions, which use 0 to indicate the 
current drive, 1 for drive A, and so on. 


The first three directory functions in the preceding list require an ASCIIZ 
string that describes the path to the desired directory. As with the handle- 
based file open and create functions, the address of the ASCIIZ string is 
passed in the DS:DX registers. On return, the carry flag is clear if the func- 
tion succeeds or set if the function failed, with an error code in the AX 
register. The directory functions can fail for a variety of reasons, but the 
most common cause of an error is that some element of the indicated path 
does not exist. 


The last function in the preceding list, Int 21H Function 47H, allows you to 
obtain an ASCIIZ path for the current directory on the specified or default 
drive. MS-DOS supplies the path string without the drive identifier or a 
leading backslash. Int 21H Function 47H is most commonly used with Int 
21H Function 19H to build fully qualified filenames. Such filenames are 
desirable because they remain valid if the user changes the current drive 
or directory. 


Section IT of this book, “MS-DOS Functions Reference,” gives detailed in- 
formation on the drive and directory control functions, 
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When you request an open operation on a file, you are implicitly perform- 
ing a search of a directory. MS-DOS examines each entry of the directory 
to find a match for the filename you have given as an argument; if the file 
is found, MS-DOS copies certain information from the directory into a 
data structure that it can use to control subsequent read or write opera- 
tions to the file. Thus, if you wish to test for the existence of a specific file, 
you need only perform an open operation and observe whether it is suc- 
cessful. (If it is, you should, of course, perform a subsequent close opera- 
tion to avoid needless expenditure of handles.) 


Sometimes you may need to perform more elaborate searches of a disk 
directory. Perhaps you wish to find all the files with a certain extension, a 
file with a particular attribute, or the names of the subdirectories of a cer- 
tain directory. Although the locations of a disk’s directories and the 
specifics of the entries that are found in them are of necessity hardware 
dependent (for example, interpretation of the field describing the starting 
location of a file depends upon the physical disk format), MS-DOS does 
provide functions that will allow examination of a disk directory in a 
hardware-independent fashion. 
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In order to search a disk directory successfully, you must understand two 
types of MS-DOS search services. The first type is the “search for first” 
function, which accepts a file specification— possibly including wildcard 
characters—and looks for the first matching file in the directory of in- 
terest. If it finds a match, the function fills a buffer owned by the request- 
ing program with information about the file; if it does not find a match, it 
returns an error flag. 


A program can call the second type of search service, called “search for 
next,” only after a successful “search for first.” If the file specification that 
was originally passed to “search for first” included wildcard characters 
and at least one matching file was present, the program can call “search 
for next” as many times as necessary to find all additional matching files. 
Like “search for first,” “search for next” returns information about the 
matched files in a buffer designated by the requesting program. When it 
can find no more matching files, “search for next” returns an error flag. 


As with nearly every other operation, MS-DOS provides two parallel sets 
of directory-searching services: 


Action FCB function Handle function 
Search for first 11H 4EH 
Search for next 12H 4FH 


The FCB directory functions allow searches to match a filename and ex- 
tension, both possibly containing wildcard characters, within the current 
directory for the specified or current drive. The handle directory func- 
tions, on the other hand, allow a program to perform searches within any 
directory on any drive, regardless of the current directory. 


Searches that use normal FCBs find only normal files. Searches that use 
extended FCBs, or the handle-type functions, can be qualified with file at- 
tributes. The attribute bits relevant to searches are as follows: 


Bit Significance 


Read-only file 

Hidden file 

System file 

Volume label 

Directory 

Archive needed (set when file modified) 
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The remaining bits of a search function’s attribute parameter should be 
zero. When any of the preceding attribute bits are set, the search function 
returns all normal files plus any files with the specified attributes, except 
in the case of the volume-label attribute bit, which receives special treat- 
ment as described later in this chapter. Note that by setting bit 4 you can 
include directories in a search, exactly as though they were files. 


Both the FCB and handle directory-searching functions require that the 
disk transfer area address be set (with Int 21H Function 1AH), before the 
call to “search for first,” to point to a working buffer for use by MS-DOS. 
The DTA address should not be changed between calls to “search for first” 
and “search for next.” When it finds a matching file, MS-DOS places the 
information about the file in the buffer and then inspects the buffer on the 
next “search for next” call, to determine where to resume the search. The 
format of the data returned in the buffer is different for the FCB and 
handle functions, so read the detailed descriptions in Section II of this 
book, “MS-DOS Functions Reference,” before attempting to interpret the 
buffer contents. 


Figures 9-2 and 9-3 provide equivalent examples of searches.for all files in 
a given directory that have the .ASM extension, one example using the 
FCB directory functions (Int 21H Functions 11H and 12H) and the other 
using the handle functions (Int 21H Functions 4EH and 4FH). (Both pro- 
grams use the handle write function with the standard output handle to 
display the matched filenames, to avoid introducing tangential differences 
in the listings.) 


(continued) 


Figure 9-2. Example of an FCB-type directory search using Int 21H Functions 11H 
and 12H. This routine displays the names of all files in the current directory that have 
the . ASM extension. 
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Figure 9-2. (continued) 
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: : ae ix: already contatr 1s 
ag “DS: DX: = ‘filename 


oe cos “DOS 


(continued) 


Figure 9-3. Example of a handle-type directory search using Int 21H Functions 4EH 
and 4FH. This routine also displays the names of all files in the current directory that 
have a .ASM extension. 
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Figure 9-3. (continued) 


Moving Files 


The rename file function that was added in MS-DOS version 2.0, Int 21H 
Function 56H, has the little-advertised capability to move a file from one 
directory to another. The function has two ASCIIZ parameters: the “old” 
and “new” names for the file. If the old and new paths differ, MS-DOS 
moves the file; if the filename or extension components differ, MS-DOS re- 
names the file. MS-DOS can carry out both of these actions in the same 
function call. 


Of course, the old and new directories must be on the same drive, because 
the file’s actual data is not moved at all; only the information that describes 
the file is removed from one directory and placed in another directory. 
Function 56H fails if the two ASCIIZ strings include different logical-drive 
codes, if the file is read-only, or if a file with the same name and location 
as the “new” filename already exists. 


The FCB-based rename file service, Int 21H Function 17H, works only on 
the current directory and cannot be used to move files. 
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Support for volume labels was first added to MS-DOS in version 2.0. A vol- 
ume label is an optional name of from 1 to 11 characters that the user 
assigns to a disk during a FORMAT operation. You can display a volume 
label with the DIR, TREE, CHKDSK, or VOL command. Beginning with 
MS-DOS version 3.0, you can use the LABEL command to add, display, or 
alter the label after formatting. In MS-DOS version 4, the FORMAT pro- 
gram also assigns a semi-random 32-bit binary ID to each disk it formats; 
you can display this value, but you cannot change it. 


The distinction between volumes and drives is important. A volume label 
is associated with a specific storage medium. A drive identifier (such as A) 
is associated with a physical device that a storage medium can be mounted 
on. In the case of fixed-disk drives, the medium associated with a drive 
identifier does not change (hence the name). In the case of floppy disks or 
other removable media, the disk accessed with a given drive identifier 
might have any volume label or none at all. 


Hence, volume labels do not take the place of the logical-drive identifier 
and cannot be used as part of a pathname to identify a file. In fact, in MS- 
DOS version 2, the system does not use volume labels internally at all. In 
MS-DOS versions 3.0 and later, a disk driver can use volume labels to 
detect whether the user has replaced a disk while a file is open; this use is 
optional, however, and is not implemented in all systems. 


MS-DOS volume labels are implemented as a special type of entry in a 
disk’s root directory. The entry contains a time-and-date stamp and has 
an attribute value of 8 (i.e., bit 3 set). Except for the attribute, a volume 
label is identical to the directory entry for a file that was created but never 
had any data written into it, and you can manipulate volume labels with 
Int 21H functions much as you manipulate files. However, a volume label 
receives special handling at several levels: 


w When you create a volume label after a disk is formatted, MS-DOS al- 
ways places it in the root directory, regardless of the current directory. 


a A disk can contain only one volume label; attempts to create additional 
volume labels (even with different names) will fail. 


= MS-DOS always carries out searches for volume labels in the root direc- 
tory, regardless of the current directory, and does not also return all 
normal files. 


In MS-DOS version 2, support for volume labels is not completely inte- 
grated into the handle file functions, and you must use extended FCBs 
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instead to manipulate volume labels. For example, the code in Figure 9-4 
searches for the volume label in the root directory of the current drive. 
You can also change volume labels with extended FCBs and the rename 
file function (Int 21H Function 17H), but you should not attempt to remove 
an existing volume label with Int 21H Function 13H under MS-DOS ver- 
sion 2, because this operation can damage the disk’s FAT in an unpredict- 
able manner. 


In MS-DOS versions 3.0 and later, you can create a volume label in the ex- 
pected manner, using Int 21H Function 3CH and an attribute of 8, and you 
can use the handle-type “search for first” function (4EH) to obtain an ex- 
isting volume label for a logical drive (Figure 9-5). However, you still must 
use extended FCBs to change a volume label. 


buff. db 


mov : dx, offset buff ee oe s : 
mov. = ah, lah -; function lah’ set 0 
int 21h "transfer to MS-! -DOS. 


"= ew search for Tabel 

Ong Eh 3 DS: ox. feed extende 
mov ae offset t xfcb_ le 

mov ah,lih——ttséC function. i = searc 

int) th ce Ao rearieren ‘to MS-DOS ~ 

emp al,0ffh . 3 search successful? 

de no. label a Jump if. no ) volume label 


Figure 9-4. A volume-label search under MS-DOS version 2, using an extended file 
control block. If the search is successful, the volume label is returned in buff, format- 
ted in the filename and extension fields of an extended FCB. 
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Figure 9-5. A volume-label search under MS-DOS version 3, using the handle-type 


file functions. If the search is successful (carry flag returned clear), the volume name 
is placed at location buff+1EH in the form of an ASCIIZ string. 
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MS-DOS disks are organized according to a rather rigid scheme that is 
easily understood and therefore easily manipulated. Although you will 
probably never need to access the special control areas of a disk directly, 
an understanding of their internal structure leads to a better understand- 
ing of the behavior and performance of MS-DOS as a whole. 


From the application programmer’s viewpoint, MS-DOS presents disk 
devices as logical volumes that are associated with a drive code (A, B, C, 
and so on) and that have a volume name (optional), a root directory, and 
from zero to many additional directories and files. MS-DOS shields the 
programmer from the physical characteristics of the medium by providing 
a battery of disk services through Int 21H. Using these services, the pro- 
grammer can create, open, read, write, close, and delete files in a uniform 
way, regardless of the disk drive’s size, speed, number of read/write 
heads, number of tracks, and so forth. 


Requests from an application program for file operations actually go 
through two levels of translation before resulting in the physical transfer 
of data between the disk device and random-access memory: 


1. Beneath the surface, MS-DOS views each logical volume, whether it is 
an entire physical unit such as a floppy disk or only a part of a fixed 
disk, as a continuous sequence of logical sectors, starting at sector 0. (A 
logical disk volume can also be implemented on other types of storage. 
For example, RAM disks map a disk structure onto an area of random- 
access memory.) MS-DOS translates an application program’s Int 21H 
file-management requests into requests for transfers of logical sectors, 
using the information found in the volume’s directories and allocation 
tables. (For those rare situations where it is appropriate, programs can 
also access logical sectors directly with Int 25H and Int 26H.) 


2. MS-DOS then passes the requests for logical sectors to the disk device’s 
driver, which maps them onto actual physical addresses (head, track, 
and sector). Disk drivers are extremely hardware dependent and are 
always written in assembly language for maximum speed. In most ver- 
sions of MS-DOS, a driver for IBM-compatible floppy- and fixed-disk 
drives is built into the MS-DOS BIOS module (IO.SYS) and is always 
loaded during system initialization; you can install additional drivers 
for non-IBM-compatible disk devices by including the appropriate 
DEVICE directives in the CONFIG.SYS file. 


Each MS-DOS logical volume is divided into several fixed-size control 
areas and a files area (Figure 10-1). The size of each control area depends 
on several factors—the size of the volume and the version of FORMAT 
used to initialize the volume, for example—but all of the information 
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Figure 10-1. Map of a typical MS-DOS logical volume. T he boot sector (logical sector 
0) contains the OEM identification, BIOS parameter block (BPB), and disk bootstrap. 
The remaining sectors are divided among an optional reserved area, one or more 
copies of the file allocation table, the root directory, and the files area. 


needed to interpret the structure of a particular logical volume can be 
found on the volume itself in the boot sector. 


The Boot Sector 


Logical sector 0, known as the boot sector, contains all of the critical infor- 
mation regarding the disk medium’s characteristics (Figure 10-2). The first 
byte in the sector is always an 80x86 jump instruction—either a normal 
intrasegment JMP (opcode 0E9H) followed by a 16-bit displacement or a 
“short” JMP (opcode 0EBH) followed by an 8-bit displacement and then 
by an NOP (opcode 90H). If neither of these two JMP opcodes is present, 
the disk has not been formatted or was not formatted for use with MS- 
DOS. (Of course, the presence of the JMP opcode does not in itself ensure 
that the disk has an MS-DOS format.) 

Following the initial JMP instruction is an 8-byte field that is reserved by 
Microsoft for OEM identification. The disk-formatting program, which is 
specialized for each brand of computer, disk controller, and medium, fills 
in this area with the name of the computer manufacturer and the manu- 
facturer’s internal MS-DOS version number. 
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OOH _ 
] E9 XX XX or EB XX 90 


OEM name and version 


(8 bytes) 


MS-DOS 
version 2.0 


MS-DOS 
version 3.0 


20H 


24H 
25H 
26H 


enn Additional 

MS-DOS 4.0 
information 
2BH 
Volume label (11 bytes) 
36H 


3EH 


MS-DOS 
Total sectors in logical volume version 4.0 
(MS-DOS 4.0 and volume size >32 MB) 


Reserved (8 bytes) 


Bootstrap 


SSeS SSS a SEL GOS eS oo TE SON Ee 


Figure 10-2. Map of the boot sector of an MS-DOS disk. Note the JMP at offset O, the 
OEM identification field, the MS-DOS version 2 compatible BIOS parameter block 
(bytes OBH-17H), the three additional WORD fields for MS-DOS version 3, the double- 
word number-of-sectors field and 32-bit binary volume ID for MS-DOS version 4.0, 
and the bootstrap code. 
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The third major component of the boot sector is the BIOS parameter block 
(BPB) in bytes OBH through 17H. (Additional fields are present in MS-DOS 
versions 3.0 and later.) This data structure describes the physical disk 
characteristics and allows the device driver to calculate the proper physi- 
cal disk address for a given logical-sector number; it also contains informa- 
tion that is used by MS-DOS and various system utilities to calculate the 
address and size of each of the disk control areas (file allocation tables and 
root directory). 


The final element of the boot sector is the disk bootstrap routine. The disk 
bootstrap is usually read into memory by the ROM bootstrap, which is ex- 
ecuted automatically when the computer is turned on. The ROM 
bootstrap is usually just smart enough to home the head of the disk drive 
(move it to track 0), read the first physical sector into RAM at a predeter- 
mined location, and jump to it. The disk bootstrap is more sophisticated. It 
calculates the physical disk address of the beginning of the files area, 
reads the files containing the operating system into memory, and transfers 
control to the BIOS module at location 0070:0000H. (See Chapter 2.) 


Figures 10-3 and 10-4 show a partial hex dump and disassembly of a PC- 
DOS 3.3 floppy-disk boot sector. 


Figure 10-3. Partial hex dump of the boot sector (track O, head O, sector 1) of a PC- 
DOS version 3.3 floppy disk. This sector contains the OEM identification, a copy of the 
BIOS parameter block describing the medium, and the bootstrap routine that reads 
the BIOS into memory and transfers control to it. See also Figures 10-2 and 10-4. 
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Figure 10-4. Partial disassembly of the boot sector shown in Figure 10-3. 


Reserved Area 


The boot sector is actually part of a reserved area that can span from one 
to several sectors. The reserved-sectors word in the BPB, at offset OEH in 
the boot sector, describes the size of this area. Remember that the number 
in the BPB field includes the boot sector itself, so if the value is 1 (as it is on 


IBM PC floppy disks), the length of the reserved area is actually 0 sectors. 


File Allocation Table 


When a file is created or extended, MS-DOS assigns it groups of disk sec- 


tors from the files area in powers of 2. These are known as allocation 
units or clusters. The number of sectors per cluster for a given medium is 


defined in the BPB and can be found at offset ODH in the disk’s boot sec- 
tor. Below are some example cluster sizes: 


Disk type Power of 2 Sectors/cluster 
5.25" 180 KB floppy disk 0 1 
5.25" 360 KB floppy disk 1 2 
PC/AT fixed disk 2 4 
PC/XT fixed disk 3 8 
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The file allocation table (FAT) is divided into fields that correspond di- 
rectly to the assignable clusters on the disk. These fields are 12 bits in MS- 
DOS versions 1 and 2 and may be either 12 bits or 16 bits in versions 3.0 
and later, depending on the size of the medium (12 bits if the disk contains 
fewer than 4087 clusters, 16 bits otherwise). 


The first two fields in the FAT are always reserved. On IBM-compatible 
media, the first 8 bits of the first reserved FAT entry contain a copy of the 
media descriptor byte, which is also found in the BPB in the boot sector. 
The second, third, and (if applicable) fourth bytes, which constitute the 
remainder of the first two reserved FAT fields, always contain OFFH. The 
currently defined IBM-format media descriptor bytes are as follows: 


a 


MS-DOS version 
where first 

Descriptor Medium supported 
OFOH 3.5" floppy disk, 2-sided, 18-sector 3.3 
OF8H Fixed disk 2.0 
OF9H 5.25" floppy disk, 2-sided, 15-sector 3.0 

3.5" floppy disk, 2-sided, 9-sector 3.2 
OFCH 5.25" floppy disk, 1-sided, 9-sector 2.0 
OFDH 5.25" floppy disk, 2-sided, 9-sector 2.0 

8" floppy disk, 1-sided, single-density 
OFEH 5.25" floppy disk, 1-sided, 8-sector 1.0 

8" floppy disk, 1-sided, single-density 

8" floppy disk, 2-sided, double-density 
OFFH 5.25" floppy disk, 2-sided, 8-sector 1.1 


En 


The remainder of the FAT entries describe the use of their corresponding 
disk clusters. The contents of the FAT fields are interpreted as follows: 


_ eC ____.._____ 


Value Meaning 

(0)000H Cluster available 
(F)FFO—C(F)FF6H Reserved cluster 

(F)FF7H Bad cluster, if not part of chain 
(F)FF8—(F)FFFH Last cluster of file 

(CX) XXX Next cluster in file 


a 


Each file’s entry in a directory contains the number of the first cluster as- 
signed to that file, which is used as an entry point into the FAT. From the 
entry point on, each FAT slot contains the cluster number of the next 
cluster in the file, until a last-cluster mark is encountered. 


At the computer manufacturer's option, MS-DOS can maintain two or 
more identical copies of the FAT on each volume. MS-DOS updates all 
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copies simultaneously whenever files are extended or the directory is 
modified. If access to a sector in a FAT fails due to a read error, MS-DOS 
tries the other copies until a successful disk read is obtained or all copies 
are exhausted. Thus, if one copy of the FAT becomes unreadable due to 
wear or a software accident, the other copies may still make it possible to 
Salvage the files on the disk. As part of its procedure for checking the in- | 
tegrity of a disk, the CHKDSK program compares the multiple copies 
(usually two) of the FAT to make sure they are all readable and consistent. 
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Following the file allocation tables is an area known in MS-DOS versions 
2.0 and later as the root directory. (Under MS-DOS version 1, it was the 
only directory on the disk.) The root directory contains 32-byte entries 
that describe files, other directories, and the optional volume label (Figure 
10-5). An entry beginning with the byte value E5H is available for reuse; it 
represents a file or directory that has been erased. An entry beginning 
with a null (zero) byte is the logical end-of-directory; that entry and all 
subsequent entries have never been used. 


OOH 
Filename Note 1 
O8H = 


a 
ES Extension 
Borns 
oe 
OBH L 
Ree 
eB 
po 


: File attribute Note 2 


OCH = 
os 
Se 
Bs 
es 
hee 
Bais 
atatats® 
Berns 
pase 
. Reserved 
Ee 
x 
ae 
eitte 
ae 
aus 
16H | 


| Time created or last updated Note 3 
18H © 

Date created or last updated Note 4 
LAH © 

Starting cluster 
1CH = 


ise 

= 

oh 

. Note 5 
SERRE Son OS ee os ea SS aS RC SER ERB Raa oo ES OTIS 


Figure 10-5. Format of a single entry in a disk di rectory. Total length is 32 bytes 
(20H bytes). 
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The root directory has a number of special properties. Its size and posi- 
tion are fixed and are determined by the FORMAT program when a disk is 
initialized. This information can be obtained from the boot sector’s BPB. If 
the disk is bootable, the first two entries in the root directory always 
describe the files containing the MS-DOS BIOS and the MS-DOS kernel. 
The disk bootstrap routine uses these entries to bring the operating sys- 
tem into memory and start it up. 


Figure 10-6 shows a partial hex dump of the first sector of the root direc- 
tory on a bootable PC-DOS 3.3 floppy disk. 


Filename Extension Attribute Reserved _ File size (in bytes) 


49 42 4D 42 49 4F 20 20,43 4F 4D/27.00 00 00 00 


PANEER AC NRE DASE BARNES RRA BRE MOEA EAS, ACER OTTE VERON ARSIN I HAMAD Moree 


2 


72 0E 02 00:54 56 00 00 


AREER ER NE RS HORE REO RIER OR SON AM CMC OSE PEN I RSaSe y 


00 00 00 00 00 00:00 60 


End of occupied Reserved Date Attribute byte for 
portion of directory Time Starting cluster volume label entry 


Figure 10-6. Partial hex dump of the first sector of the root directory for a PC-DOS 
3.3 disk containing the three system files and a volume label. 


The Files Area 


The remainder of the volume after the root directory is known as the files 
area. MS-DOS views the sectors in this area as a pool of clusters, each 
containing one or more logical sectors, depending on the disk format. 
Each cluster has a corresponding entry in the FAT that describes its cur- 
rent use: available, reserved, assigned to a file, or unusable (because of 
defects in the medium). Because the first two fields of the FAT are 
reserved, the first cluster in the files area is assigned the number 2. 
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When a file is extended under versions 1 and 2, MS-DOS searches the FAT 
from the beginning until it finds a free cluster (designated by a zero FAT 
field); it then changes that FAT field to a last-cluster mark and updates the 
previous last cluster of the file’s chain to point to the new last cluster. 
Under versions 3.0 and later, however, MS-DOS searches the FAT from the 
most recently allocated cluster; this reduces file fragmentation and im- 
proves overall access times. 


Directories other than the root directory are simply a special type of file. 
Their storage is allocated from the files area, and their contents are 32- 
byte entries—in the same format as those used in the root directory— 
that describe files or other directories. Directory entries that describe 
other directories contain an attribute byte with bit 4 set, zero in the file- 
length field, and the date and time that the directory was created (Figure 
10-7). The first cluster field points, of course, to the first cluster in the files 
area that belongs to the directory. (The directory’s other clusters can be 
found only by tracing through the FAT.) 


All directories except the root directory contain two special directory en- 
tries with the names . and ... MS-DOS puts these entries in place when it 
creates a directory, and they cannot be deleted. The . entry is an alias for 
the current directory; its cluster field points to the cluster in which it is 


Subdirectory name Attribute byte indicating a subdirectory entry Reserved 


0 00 


Reserved Date subdirectory created File size indicated as zero bytes 


Time subdirectory created Starting cluster of subdirectory file 


Figure 10-7. Extract from the root directory of an MS-DOS disk, showing the entry 
for a subdirectory named MYDIR. Bit 4 in the attribute byte is set, the cluster field 
points to the first cluster of the subdirectory file, the date and time stamps are valid, 
but the file length is zero. 
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found. The .. entry is an alias for the directory’s parent (the directory 
immediately above it in the tree structure); its cluster field points to the 
first cluster of the parent directory. If the parent is the root directory, the 
cluster field of the .. entry contains zero (Figure 10-8). 


Alias for current directory Attribute bytes indicating a subdirectory 


20 20 20 20 20 20 20 107 


Alias for parent directory 


Figure 10-8. Hex dump of the first block of the directory MYDIR. Note the. and.. 
entries. This directory contains exactly one file, MY FILE.DAT. 
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Now that we understand how the disk is structured, let’s see how we can 
use this knowledge to find a FAT position from a cluster number. 


If the FAT has 12-bit entries, use the following procedure: 


1. Use the directory entry to find the starting cluster of the file in 
question. 


2. Multiply the cluster number by 1.5. 


3. Use the integral part of the product as the offset into the FAT and move 
the word at that offset into a register. Remember that a FAT position 
can span a physical disk-sector boundary. 


4. If the product is a whole number, AND the register with OFFFH. 
5. Otherwise, “logical shift” the register right 4 bits. 


6. If the result is a value from OFF8H through OFFFH, the file has no 
more clusters. Otherwise, the result is the number of the next cluster 
in the file. 
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On disks with at least 4087 clusters formatted under MS-DOS version 3.0 
or later, the FAT entries use 16 bits, and the extraction of a cluster number 
from the table is much simpler: 


1. Use the directory entry to find the starting cluster of the file in 
question. 


2. Multiply the cluster number by 2. 


3. Use the product as the offset into the FAT and move the word at that 
offset into a register. 


4. If the result is a value from OFFF8H through OFFFFH, the file has no 


more clusters. Otherwise, the result is the number of the next cluster in 
the file. 


To convert cluster numbers to logical sectors, subtract 2, multiply the 
result by the number of sectors per cluster, and add the logical-sector 
number of the beginning of the data area (this can be calculated from the 
information in the BPB). 


As an example, let’s work out the disk location of the file IBMBIO.COM, 
which is the first entry in the directory shown in Figure 10-6. First, we 
need some information from the BPB, which is in the boot sector of the 
medium. (See Figures 10-3 and 10-4.) The BPB tells us that there are 


ws 512 bytes per sector 

= 2sectors per cluster 

= 2sectors per FAT 

s 2FATs 

w 112 entries in the root directory 


From the BPB information, we can calculate the starting logical-sector 
number of each of the disk’s control areas and the files area by construct- 
ing a table, as follows: 


re 
Area Length (sectors) Sector numbers 
Boot sector 1 00H 
2 FATs * 2 sectors/FAT 4 01H-—04H 
112 directory entries 7 0SH-OBH 
«32 bytes/entry 
/ 512 bytes/sector 
Total sectors occupied by 12 
bootstrap, FATs, and root 
directory 
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Therefore, the first sector of the files area is 12 (OCH). 


The word at offset 01AH in the directory entry for IBMBIO.COM gives us 
the starting cluster number for that file: cluster 2. To find the logical-sector 
number of the first block in the file, we can follow the procedure given 
earlier: 


1. Cluster number — 2 = 2—2 = 0. 
2. Multiply by sectors per cluster = 0 * 2 = 0. 
3. Add logical-sector number of start of the files area = 0 + OCH = OCH. 


So the calculated sector number of the beginning of the file I]BMBIO.COM 
is OCH, which is exactly what we expect knowing that the FORMAT pro- 
gram always places the system files in contiguous sectors at the beginning 
of the data area. 


Now let’s trace IBMBIO.COM’s chain through the file allocation table 
(Figures 10-9 and 10-10). This will be a little tedious, but a detailed under- 
standing of the process is crucial. In an actual program, we would first 
read the boot sector using Int 25H, then calculate the address of the FAT 
from the contents of the BPB, and finally read the FAT into memory, again 
using Int 25H. 


From IBMBIO.COM’s directory entry, we already know that the first clus- 
ter in the file is cluster 2. To examine that cluster’s entry in the FAT, we 
multiply the cluster number by 1.5, which gives 0003H as the FAT offset, 
and fetch the word at that offset (which contains 4003H). Because the 
product of the cluster and 1.5 is a whole number, we AND the word from 
the FAT with OFFFH, yielding the number 3, which is the number of the 
second cluster assigned to the file. 


Figure 10-9. Hex dump of the first block of the file allocation table (track O, head O, 
sector 2) for the PC-DOS 3.3 disk whose root di rectory is shown in Figure 10-6. Notice 
that the first byte of the FAT contains the media descriptor byte for a 5.25-inch, 
2-sided, 9-sector floppy disk. 
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Figure 10-10. Assembly-language procedure to access the file allocation table 
(assumes 12-bit FAT fields). Given a cluster number, the procedure returns the con- 
tents of that cluster’s FAT entry in the AX register. This simple example ignores the fact 
that EAT entries can span sector boundaries. 


To examine cluster 3’s entry in the FAT, we multiply 3 by 1.5, which gives 
4.5, and fetch the word at offset 0004H (which contains 0040H). Because 
the product of 3 and 1.5 is not a whole number, we shift the word right 
4 bits, yielding the number 4, which is the number of the third cluster 
assigned to IBMBIO.COM. 


In this manner, we can follow the chain through the FAT until we come to 
a cluster (number 23, in this case) whose FAT entry contains the value 
OFFFH, which is an end-of-file marker in FAT's with 12-bit entries. 


We have now established that the file IBMBIO.COM contains clusters 2 
through 23 (02H-17H), from which we can calculate that logical sectors 
OCH through 38H are assigned to the file. Of course, the last cluster may 
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be only partially filled with actual data; the portion of the last cluster used 
is the remainder of the file’s size in bytes (found in the directory entry) 
divided by the bytes per cluster. 
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Fixed disks have another layer of organization beyond the logical volume 
structure already discussed: partitions. The FDISK utility divides a fixed 
disk into one or more partitions consisting of an integral number of 
cylinders. Each partition can contain an independent file system and, for 
that matter, its own copy of an operating system. 


The first physical sector on a fixed disk (track 0, head 0, sector 1) contains 
the master boot record, which is laid out as follows: 


ee 
Bytes Contents 
a 


000-1BDH Reserved 

1BE-1CDH Partition #1 descriptor 
1CE-1DDH Partition #2 descriptor 
1DE-1EDH Partition #3 descriptor 
1EE-1FDH Partition #4 descriptor 
1FE-1FFH Signature word (AA55H) 


5 


The partition descriptors in the master boot record define the size, loca- 
tion, and type of each partition, as follows: 


ener 


Byte(s) Contents 

00H Active flag (0 = not bootable, 80H = bootable) 
01H Starting head 

02H-—03H Starting cylinder/sector 

04H Partition type 


OOH not used 

01H FAT file system, 12-bit FAT entries 

04H FAT file system, 16-bit FAT entries 

05H extended partition 

06H “huge partition” (MS-DOS versions 4.0 and later) 


05H Ending head 

06H-07H Ending cylinder/sector 

08H-—0BH Starting sector for partition, relative to beginning of disk 
OCH-OFH Partition length in sectors 


i 


The active flag, which indicates that the Partition is bootable, can be set 
on only one partition at a time. 
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MS-DOS treats partition types 1, 4, and 6 as normal logical volumes and 
assigns them their own drive identifiers during the system boot process. 
Partition type 5 can contain multiple logical volumes and has a special 
extended boot record that describes each volume. The FORMAT utility 
initializes MS-DOS fixed-disk partitions, creating the file system within 
the partition (boot record, file allocation table, root directory, and files 
area) and optionally placing a bootable copy of the operating system in 
the file system. 


Figure 10-11 contains a partial hex dump of a master block from a fixed 
disk formatted under PC-DOS version 3.3. This dump illustrates the parti- 


tion descriptors for a normal partition with a 16-bit FAT and an extended 
partition. 


Type byte for partition 1 Active (bootable) partition flag 


ire 0: pt ge Ses ee © Paves phate eines 
00 00 00 00 00 00 


Type byte for partition 2 Signature word First partition entry 
Second partition entry 
Third partition entry 
Fourth partition entry 


Figure 10-11. A partial hex dump of a master block from a fixed disk formatted 
under PC-DOS version 3.3. This disk contains two partitions. The first partition has a 
16-bit FAT and is marked “active” to indicate that it contains a bootable copy of PC- 
DOS. The second partition is an “extended” partition. The third and fourth partition 
entries are not used in this example. 
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Current versions of MS-DOS can manage as much as 1 megabyte of con- 
tiguous random-access memory. On IBM PCs and compatibles, the 
memory occupied by MS-DOS and other programs starts at address 0000H 
and may reach as high as address 09FFFFH; this 640 KB area of RAM is 
sometimes referred to as conventional memory. Memory above this ad- 
dress is reserved for ROM hardware drivers, video refresh buffers, and the 
like. Computers that are not IBM compatible may use other memory 
layouts. 


The RAM area under the control of MS-DOS is divided into two major 
sections: 


= The operating-system area 
= The transient-program area 


The operating-system area starts at address 0000H—that is, it occupies 
the lowest portion of RAM. It holds the interrupt vector table, the operat- 
ing system proper and its tables and buffers, any additional installable 
drivers specified in the CONFIG.SYS file, and the resident part of the 
COMMAND.COM command interpreter. The amount of memory oc- 
cupied by the operating-system area varies with the version of MS-DOS 
used, the number of disk buffers, the size of installed device drivers, and 
so forth. 


The transient-program area (TPA), sometimes called the memory arena, 
is the remainder of memory above the operating-system area. The 
memory arena is dynamically allocated in blocks called arena entries. 
Each arena entry has a special control structure called an arena header, 
and all of the arena headers are chained together. Three MS-DOS Int 21H 
functions allow programs to allocate, resize, and release blocks of 
memory from the TPA: 


SSeS eeeceenas 


Function Action 


48H Allocate memory block. 
49H Release memory block. 
4AH Resize memory block. 


Ses 
MS-DOS itself uses these functions when loading a program from disk at 
the request of COMMAND.COM or another program. The EXEC function, 
which is the MS-DOS program loader, calls Int 21H Function 48H to allo- 
cate a memory block for the loaded program’s environment and another 
for the program itself and its program segment prefix. It then reads the 
program from the disk into the assigned memory area. When the program 
terminates, MS-DOS calls Int 21H Function 49H to release all memory 
owned by the program. 


Programming for MS-DOS 


Transient programs can also employ the MS-DOS memory-management 
functions to dynamically manage the memory available in the TPA. Proper 
use of these functions is one of the most important criteria of whether a 
program is well behaved under MS-DOS. Well-behaved programs are 
most likely to be portable to future versions of the operating system and 
least likely to cause interference with other processes under multitasking 
user interfaces such as Microsoft Windows. 


Using the Memory-Allocation Functions 
The memory-allocation functions have two common uses: 


a To shrink a program’s initial memory allocation so that there is enough 
room to load and execute another program under its control. 


a To dynamically allocate additional memory required by the program 
and to release the same memory when it is no longer needed. 


Shrinking the Initial Memory Allocation 
Although many MS-DOS application programs simply assume they own 
all memory, this assumption is a relic of MS-DOS version 1 (and CP/M), 
which could support only one active process at a time. Well-behaved MS- 
DOS programs take pains to modify only memory that they actually own 
and to release any memory that they don’t need. 


Unfortunately, under current versions of MS-DOS, the amount of memory 
that a program will own is not easily predicted in advance. It turns out that 
the amount of memory allocated to a program when it is first loaded de- 
pends upon two factors: 


a The type of file the program is loaded from 
a The amount of memory available in the TPA 


MS-DOS always allocates all of the largest available memory block in the 
TPA to programs loaded from .COM (memory-image) files. Because .COM 
programs contain no file header that can pass segment and memory-use 
information to MS-DOS, MS-DOS simply assumes the worst case and gives 
such a program everything. MS-DOS will load the program as long as 
there is an available memory block as large as the size of the file plus 256 
bytes for the PSP and 2 bytes for the stack. The .COM program, when it 
receives control, must determine whether enough memory is available to 
carry out its functions. 
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MS-DOS uses more complicated rules to allocate memory to programs 
loaded from .EXE files. First, of course, a memory block large enough to 
hold the declared code, data, and stack segments must be available in the 
TPA. In addition, the linker sets two fields in a .EXE file’s header to inform 
MS-DOS about the program’s memory requirements. The first field, 
MIN_ALLOC, defines the minimum number of paragraphs required by 
the program, in addition to those for the code, data, and stack segments, 
The second, MAX_ALLOC, defines the maximum number of paragraphs 
of additional memory the program would use if they were available. 


When loading a .EXE file, MS-DOS first attempts to allocate the number of 
paragraphs in MAX_ALLOC plus the number of paragraphs required by 
the program itself. If that much memory is not available, MS-DOS assigns 
all of the largest available block to the program, provided that this is at 
least the amount specified by MIN_ALLOC plus the size of the program 
image. If that condition is not satisfied, the program cannot be executed. 


After a .COM or .EXE program is loaded and running, it can use Int 21H 
Function 4AH (Resize Memory Block) to release all the memory it does 
not immediately need. This is conveniently done right after the program 
receives control from MS-DOS, by calling the resize function with the seg- 
ment of the program’s PSP in the ES register and the number of para- 
graphs that the program requires to run in the BX register (Figure 11-1). 


(continued) 


Figure 11-1. An example of a .COM program releasing excess memory after it 
receives control from MS-DOS. Int 21H Function 4AH is called with ES pointing to the 
program's PSP and BX containing the number of paragraphs that the program needs 
to execute. In this case, the new size for the program’s memory block is calculated as 
the program image size plus the size of the PSP (256 bytes), rounded up to the next 
paragraph. .EXE programs use similar code. 
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Figure 11-1. continued 


Dynamic Allocation of Additional Memory 


When a well-behaved program needs additional memory space—for an 
I/O buffer or an array of intermediate results, for example—it can call Int 
21H Function 48H (Allocate Memory Block) with the desired number of 
paragraphs. If a sufficiently large block of unallocated memory is avail- 
able, MS-DOS returns the segment address of the base of the assigned area 
and clears the carry flag (0), indicating that the function was successful. 


If no unallocated block of sufficient size is available, MS-DOS sets the 
carry flag (1), returns an error code in the AX register, and returns the size 
(in paragraphs) of the largest block available in the BX register (Figure 
11-2). In this case, no memory has yet been allocated. The program can 
use the value returned in the BX register to determine whether it can con- 
tinue in a “degraded” fashion, with less memory. If it can, it must call Int 
21H Function 48H again to allocate the smaller memory block. 


When the MS-DOS memory manager is searching the chain of arena 
headers to satisfy a memory-allocation request, it can use one of the fol- 
lowing strategies: 


First fit: Use the arena entry at the lowest address that is large enough 
to satisfy the request. 


Best fit: Use the smallest arena entry that will satisfy the request, 
regardless of its location. 


Last fit: Use the arena entry at the highest address that is large enough 
to satisfy the request. 
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Figure 11-2. Example of dynamic memory allocation. The program requests a 32 KB 
memory block from MS-DOS, fills it with —1s, writes it to disk, and then releases it. 
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If the arena entry selected is larger than the size requested, MS-DOS di- 
vides it into two parts: one block of the size requested, which is assigned 
to the program that called Int 21H Function 48H, and an unowned block 
containing the remaining memory. 


The default MS-DOS allocation strategy is first fit. However, under MS- 
DOS versions 3.0 and later, an application program can change the strat- 
egy with Int 21H Function 58H. 


When a program is through with an allocated memory block, it should use 
Int 21H Function 49H to release the block. If it does not, MS-DOS will 
automatically release all memory allocations for the program when it 
terminates. 


Arena Headers 


Microsoft has not officially documented the internal structure of arena 
headers for the outside world at present. This is probably to deter pro- 
grammers from trying to manipulate their memory allocations directly in- 
stead of through the MS-DOS functions provided for that purpose. 


Arena headers have identical structures in MS-DOS versions 2 and 3. They 
are 16 bytes (one paragraph) and are located immediately before the 
memory area that they control (Figure 11-3). An arena header contains the 
following information: 


= A byte signifying whether the header is a member or the last entry in 
the entire chain of such headers 


® A word indicating whether the area it controls is available or whether it 
already belongs to a program Cif the latter, the word points to the pro- 
gram’s PSP) 


® A word indicating the size (in paragraphs) of the controlled memory 
area (arena entry) 


MS-DOS inspects the chain of arena headers whenever the program re- 
quests a memory-block allocation, modification, or release function, or 
when a program is EXEC’d or terminated. If any of the blocks appear to 
be corrupted or if the chain is broken, MS-DOS displays the dreaded 
message 


Memory allocationerror 


and halts the system. 
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In the example illustrated in Figure 11-3, COMMAND.COM originally 
loaded PROGRAMI1.COM into the TPA and, because it was a .COM file, 
COMMAND.COM allocated it all of the TPA, controlled by arena header 
#1. PROGRAMI1.COM then used Int 21H Function 44H (Resize Memory 
Block) to shrink its memory allocation to the amount it actually needed to 
run and loaded and executed PROGRAM2.EXE with the EXEC function 
(int 21H Function 4BH). The EXEC function obtained a suitable amount of 
memory, controlled by arena header #2, and loaded PROGRAM2.EXE 
into it. PROGRAM2.EXE, in turn, needed some additional memory to 
store some intermediate results, so it called Int 21H Function 48H (Allo- 
cate Memory Block) to obtain the area controlled by arena header #3. The 
highest arena header (#4) controls all of the remaining TPA that has not 
been allocated to any program. 
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Figure 11-3. An example diagram of MS-DOS arena headers and the transient- 


program area. The environment blocks and their associated headers have been 
omitted from this figure to increase its clarity. 
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controlled by MS-DOS 


Lotus/Intel/Microsoft Expanded Memory 


When the IBM Personal Computer and MS-DOS were first released, the 
640 KB limit that IBM placed on the amount of RAM that could be directly 
managed by MS-DOS seemed almost unimaginably huge. But as MS-DOS 
has grown in both size and capabilities and the popular applications have 
become more powerful, that 640 KB has begun to seem a bit crowded. 
Although personal computers based on the 80286 and 80386 have the po- 
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=f 8086/ 8088-based computers and MS-DOS. 


At the spring COMDEX in 1985, Lotus Development Corporation and Intel 
Corporation jointly announced the Expanded Memory Specification 3.0 
(EMS), which was designed to head off rapid obsolescence of the older 
PCs because of limited memory. Shortly afterward, Microsoft announced 
that it would support the EMS and would enhance Microsoft Windows to 
use the memory made available by EMS hardware and software. EMS ver- 
sions 3.2 and 4.0, released in fall 1985 and summer 1987, expanded support 
for multitasking operating systems. 


The LIM EMS (as it is usually known) has been an enormous success. EMS 
memory boards are available from scores of manufacturers, and “EMS- 
aware” software—especially spreadsheets, disk caches, and terminate- 
and-stay-resident utilities—has become the rule rather than the 
exception. 


What Is Expanded Memory? 

The Lotus/Intel/Microsoft Expanded Memory Specification is a functional 
definition of a bank-switched memory-expansion subsystem. It consists 
of hardware expansion modules and a resident driver program specific to 
those modules. In EMS versions 3.0 and 3.2, the expanded memory is 
made available to application software as 16 KB pages mapped into a con- 
tiguous 64 KB area called the page frame, somewhere above the main 
memory area used by MS-DOS/PC-DOS (0-640 KB). The exact location of 
the page frame is user configurable, so it need not conflict with other 
hardware options. In EMS version 4.0, the pages may be mapped 
any where in memory and can have sizes other than 16 KB. 


The EMS provides a uniform means for applications to access as much as 8 
megabytes of memory (32 megabytes in EMS 4.0). The supporting soft- 
ware, which is called the Expanded Memory Manager (EMM), provides a 
hardware-independent interface between application software and the 
expanded memory board(s). The EMM is supplied in the form of an 
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installable device driver that you link into the MS-DOS/PC-DOS system 
by adding a line to the CONFIG.SYS file on the system boot disk. 


Internally, the Expanded Memory Manager consists of two major por- 
tions, which may be referred to as the driver and the manager. The 
driver portion mimics some of the actions of a genuine installable device 
driver, in that it includes initialization and output status functions and a 
valid device header. The second, and major, portion of the EMM is the 
true interface between application software and the expanded-memory 
hardware. Several classes of services are provided: 


® Verification of functionality of hardware and software modules 
# Allocation of expanded-memory pages 

= Mapping of logical pages into the physical page frame 

" Deallocation of expanded-memory pages 

® Support for multitasking operating systems 


Application programs communicate with the EMM directly, by means of 
software Int 67H. MS-DOS versions 3.3 and earlier take no part in (and in 
fact are completely oblivious to) any expanded-memory manipulations 
that may occur. MS-DOS version 4.0 and Microsoft Windows, on the other 
hand, are “EMS-aware” and can use the EMS memory when it is available. 


Expanded memory should not be confused with extended memory. Ex- 
tended memory is the term used by IBM to refer to the memory at physical 
addresses above 1 megabyte that can be accessed by an 80286 or 80386 
CPU in protected mode. Current versions of MS-DOS run the 80286 and 
80386 in real mode (8086-emulation mode), and extended memory is 
therefore not directly accessible. 
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An application program can use either of two methods to test for the exis- 
tence of the Expanded Memory Manager: 


= Issue an open request (Int 21H Function 3DH) using the guaranteed 
device name of the EMM driver: EMMXXXX0. If the open function 
succeeds, either the driver is present or a file with the same name coin- 
cidentally exists on the default disk drive. To rule out the latter, the 
application can use IOCTL (Int 21H Function 44H) subfunctions 00H 
and 07H to ensure that EMM is present. In either case, the application 
should then use Int 21H Function 3EH to close the handle that was ob- 
tained from the open function, so that the handle can be reused for 
another file or device. 
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Use the address that is found in the Int 67H vector to inspect the device 
header of the presumed EMM. Interrupt handlers and device drivers 
must use this method. If the EMM is present, the name field at offset 
OAH of the device header contains the string EMMXXXX0. This ap- 
proach is nearly foolproof and avoids the relatively high overhead of 
an MS-DOS open function. However, it is somewhat less well behaved 
because it involves inspection of memory that does not belong to the 
application. 


These two methods of testing for the existence of the Expanded Memory 
Manager are illustrated in Figures 11-4 and 11-5. 


(continued) 


Figure 11-4. Testing for the Expanded Memory Manager by means of the MS-DOS 
open and IOCTL functions. 
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Figure 11-4. continued 


Figure 11-5. Testing for the Expanded Memory Manager by inspection of the name 
field in the driver's device header. 
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Using Expanded Memory 


After establishing that the memory-manager software is present, the ap- 
plication program communicates with it directly by means of the “user in- 
terrupt” 67H, bypassing MS-DOS/PC-DOS. The calling sequence for the 
EMM is as follows: 


In general, AH contains the EMM function number, AL holds the subfunc- 
tion number (if any), BX holds a number of pages Gf applicable), and DX 
contains an EMM handle. Registers DS:SI and ES:DI are used to pass the 
addresses of arrays or buffers. Section IV of this book, “Lotus/Intel/ 
Microsoft EMS Functions Reference,” details each of the expanded 
memory functions. 


Upon return from an EMM function, the AH register contains zero if the 
function was successful; otherwise, it contains an error code with the most 
significant bit set (Figures 11-6 and 11-7). Other values are typically 
returned in the AL and BX registers or in a user-specified buffer. 


Error code Meaning 

00H Function successful. 

80H Internal error in Expanded Memory Manager software (could be 
caused by corrupted memory image of driver). 

81H Malfunction in expanded-memory hardware. 

82H Memory manager busy. 

83H Invalid handle. 

84H Function requested by application not defined. 

85H No more handles available. 

86H Error in save or restore of mapping context. 

87H Allocation request specified more logical pages than physically 
available in system, no pages allocated. 

88H Allocation request specified more logical pages than currently 


available in system (request does not exceed physical pages 
that exist, but some are already allocated to other handles), 
no pages allocated. 


(continued) 


Figure 11-6. Expanded Memory Manager error codes common to EMS versions 3.0, 
3.2, and 4.0. After a call to EMM, the AH register contains zero if the function was 
successful or an error code in the range 80H through 8FH if the function failed. 
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Figure 11-6. continued 
a 


Error code Meaning 

89H Zero pages; cannot be allocated. 

8AH Logical page requested to be mapped located outside range of 
logical pages assigned to handle. 

8BH Illegal physical page number in mapping request (not in range 
0-3). 

8CH Page-mapping hardware-state save area full. 

8DH Save of mapping context failed; save area already contains context 
associated with requested handle. 

8EH Restore of mapping context failed; save area does not contain 
context for requested handle. 

8FH Subfunction parameter not defined. 


EEE | 


Error code Meaning 

90H Attribute type not defined. 

91H Feature not supported. 

92H Source and destination memory regions have same handle and 


overlap; requested move was performed, but part of source 
region was overwritten. 


93H Specified length for source or destination memory region is longer 
than actual allocated length. 

94H Conventional-memory region and expanded-memory region 
overlap. 

95H Specified offset is outside logical page. 

96H Region length exceeds 1 MB. _ 

97H Source and destination memory regions have same handle and 
overlap; exchange cannot be performed. 

98H Memory source and destination types undefined. 

99H This error code currently unused. 

9AH Alternate map or DMA register sets supported, but the alternate 
register set specified is not supported. 

9BH Alternate map or DMA register sets supported, but all alternate 
register sets currently allocated. 

9CH Alternate map or DMA register sets not supported, and specified 
alternate register set not zero. 

9DH Alternate map or DMA register sets supported, but alternate 


register set specified is either not defined or not allocated. 


(continued) 


Figure 11-7. Expanded Memory Manager error codes unique to EMS version 4.0. 
Most of these errors are related to the EMS functions for use by operating systems and 
would not normally be encountered by application programs. 
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Figure 11-7. continued 
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Error code Meaning 

9EH Dedicated DMA channels not supported. 

9FH Dedicated DMA channels supported, but specified DMA 
channel not supported. 

AOH No handle found for specified name. 

A1H Handle with this name already exists. 

A2H Memory address wrap; sum of the source or destination 
region base address and length exceeds 1 MB. 

A3H Invalid pointer passed to function, or contents of source array 
corrupted. 

A4H Access to function denied by operating system. 


a 


An application program that uses expanded memory should regard that 
memory as a system resource, like a file or a device, and employ only the 
documented EMM services to allocate, access, and release expanded- 
memory pages. Such a program can use the following general strategy: 


1. 


Establish the presence of the Expanded Memory Manager by one of 
the two methods demonstrated in Figures 11-4 and 11-5. 


_ After the driver is known to be present, check its operational status 


with EMS Function 40H. 


_ Check the version number of EMM with EMS Function 46H, to ensure 


that all services the application will request are available. 


. Obtain the segment of the page frame used by EMM with EMS Func- 


tion 41H. 


. Allocate the desired number of expanded-memory pages with EMS 


Function 43H. If the allocation is successful, EMM returns a handle that 
the application can use to refer to the expanded-memory pages that it 
owns. This step is exactly analogous to opening a file and using the 


handle obtained from the open function for read/write operations on 
the file. 


. If the requested number of pages are not available, the application can 


query EMM for the actual number of pages available (EMS Function 
42H) and determine whether it can continue. 


. After the application has successfully allocated the needed number of 


expanded-memory pages, it uses EMS Function 44H to map logical 
pages in and out of the physical page frame in order to store and 
retrieve data in expanded memory. 
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8. When the program finishes using its expanded-memory pages, it must 
release them by calling EMS Function 45H. Otherwise, the pages will 
be lost to use by other programs until the system is restarted. 


Figure 11-8 shows a skeleton program that illustrates this general approach. 


An interrupt handler or device driver that uses EMS follows the same gen- 
eral procedure outlined in steps 1 through 8, with a few minor variations. 
It may need to acquire an EMS handle and allocate pages before the 
operating system is fully functional; in particular, you cannot assume that 
the MS-DOS Open File or Device, IOCTL, and Get Interrupt Vector func- 
tions are available. Thus, such a handler or driver must use a modified ver- 
sion of the “get interrupt vector” technique (Figure 11-5) to test for the 
existence of EMM, fetching the contents of the Int 67H vector directly. 


A device driver or interrupt handler typically owns its expanded-memory 
pages permanently (until the system is restarted) and never deallocates 
them. Such a program must also take care to save and restore EMM’s page- 
mapping context (EMS Functions 47H and 48H) whenever it accesses 


expanded memory, so that use of EMS by a foreground program will not 
be disturbed. 


The EMM relies on the good behavior of application software to avoid the 
corruption of expanded memory. If several applications that use expand- 
ed memory are running under a multitasking manager such as Microsoft 
Windows and one or more of them does not abide strictly by EMM con- 
ventions, the data of some or all of the applications may be destroyed. 


(continued) 


Figure 11-8. A program illustrating the general strategy for using expanded memory. 
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Figure 11-8. continued 
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Extended Memory 
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Extended memory is RAM storage at addresses above 1 megabyte 
(100000H) that can be accessed by an 80286 or 80386 processor running in 
protected mode. IBM PC/AT- and PS/2-—compatible machines can 
(theoretically) have as much as 15 MB of extended memory installed, in 
addition to the usual 1 MB of conventional memory. 


Protected-mode operating systems such as Microsoft KENIX or MS OS/2 
can use extended memory for execution of programs. MS-DOS, on the 
other hand, runs in real mode on an 80286 or 80386, and programs run- 
ning under its control cannot ordinarily execute from extended memory 
or even address that memory for storage of data. However, the ROM BIOS 
contains two routines that allow real-mode programs restricted access to 
extended memory: 


SSS ees 


ROM BIOS function Action 
Int 15H Function 87H Move extended-memory block. 
Int 15H Function 88H Get extended-memory size. 


—_— ees“ 


These routines can be used by electronic disks (RAMdisks) and by other 
programs that want to use extended memory for fast storage and retrieval 
of information that would otherwise have to be written to a slower physi- 
cal disk drive. Section III of this book, “IBM ROM BIOS and Mouse Func- 
tions Reference,” documents both of these functions. 


You should use these ROM BIOS routines with caution. Data stored in ex- 
tended memory is, of course, volatile; it is lost if the machine is turned off. 
The transfer of data to or from extended memory involves a switch from 
real mode to protected mode and back, which is a relatively slow process 
on 80286-based machines; in some cases it is only marginally faster than 
actually reading the data from a fixed disk. In addition, programs that use 
the ROM BIOS extended-memory functions are not compatible with the 
MS-DOS compatibility mode of MS OS/2. 


Finally, a major deficit in these ROM BIOS functions is that they do not 
make any attempt to arbitrate between two or more programs or drivers 
that are using extended memory for temporary storage. For example, if an 
application program and an installed RAMdisk driver attempt to put data 
in the same area of extended memory, no error will be returned to either 
program, but the data of one or both may be destroyed. 


Figure 11-9 shows an example of the code necessary to transfer data to and 
from extended memory. 
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Figure 11-9. Moving blocks of data between conventional memory and extended 
memory, using the ROM BIOS extended-memory functions. For additional informa- 
tion on the format of the block move descriptor table, see the entry for Int 15H 
Function 87H in Section III of this book, ‘IBM ROM BIOS and Mouse Functions Refer- 


ence.” Note that you must specify the extended-memory address as a 32-bit linear 
address rather than as a segment and offset. 
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Figure 11-9. continued 


(continued) 
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Figure 11-9. continued 
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Chapter 12 


The EXEC Function 


The MS-DOS EXEC function (Int 21H Function 4BH) allows a program 
(called the parent) to load any other program (called the child) from a 
storage device, execute it, and then regain control when the child pro- 
gram is finished. 


A parent program can pass information to the child in a command line, in 
default file control blocks, and by means of a set of strings called the envi- 
ronment block (discussed later in this chapter). All files or devices that the 
parent opened using the handle file-management functions are duplicated 
in the newly created child task; that is, the child inherits all the active 
handles of the parent task. Any file operations on those handles by the 
child, such as seeks or file I/O, also affect the file pointers associated with 
the parent’s handles. 


MS-DOS suspends execution of the parent program until the child pro- 
gram terminates. When the child program finishes its work, it can pass an 
exit code back to the parent, indicating whether it encountered any errors. 
It can also, in turn, load other programs, and so on through many levels of 
control, until the system runs out of memory. 


The MS-DOS command interpreter, COMMAND.COM, uses the EXEC 
function to run its external commands and other application programs. 
Many popular commercial programs, such as database managers and 
word processors, use EXEC to run other programs (spelling checkers, for 
example) or to load a second copy of COMMAND.COM, thereby allowing 
the user to list directories or copy and rename files without closing all 
the application files and stopping the main work in progress. EXEC can 
also be used to load program overlay segments, although this use is 
uncommon. 
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In order for a parent program to use the EXEC function to load a child 
program, sufficient unallocated memory must be available in the transient 
program area. 


. When the parent itself was loaded, MS-DOS allocated it a variable amount 


of memory, depending upon its original file type—.COM or .EXE—and 
any other information that was available to the loader. (See Chapter 11 for 
further details.) Because the operating system has no foolproof way of 
predicting how much memory any given program will require, it gener- 
ally allocates far more memory to a program than is really necessary. 
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Therefore, a prospective parent program’s first action should be to use Int 
21H Function 4AH (Resize Memory Block) to release any excess memory 
allocation of its own to MS-DOS. In this case, the program should call Int 
21H Function 4AH with the ES register pointing to the program segment 
prefix of the program releasing memory and the BX register containing 
the number of paragraphs of memory to retain for that program. (See 
Figure 11-1 for an example.) 


CO WARNING A .COM program must move its stack to a safe area if 
it is reducing its memory allocation to less than 64 KB. 


Requesting the EXEC Function 


To load and execute a child program, the parent must execute an Int 21H 
with the registers set up as follows: 


AH = 4BH 
AL = 00H (subfunction to load child program) 
DS:DX = segment:offset of pathname for child program 


ES:BX = segment:offset of parameter block 


The parameter block, in turn, contains addresses of other information 
needed by the EXEC function. 


The Program Name 
The name of the program to be run, which the calling program provides 
to the EXEC function, must be an unambiguous file specification (no wild- 
card characters) and must include an explicit .COM or .EXE extension. If 
the path and disk drive are not supplied in the program name, MS-DOS 
uses the current directory and default disk drive. (The sequential search 
for .COM, .EXE, and .BAT files in all the locations listed in the PATH 
variable is not a function of EXEC, but rather of the internal logic of 
COMMAND.COM.) 


You cannot EXEC a batch file directly; instead, you must EXEC a copy of 
COMMAND.COM and pass the name of the batch file in the command 
tail, along with the /C switch. 
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The Parameter Block 


The parameter block contains the addresses of four data objects: 
a The environment block 

= The command tail 

= Two default file control blocks 


The space reserved in the parameter block for the address of the environ- 
ment block is only 2 bytes and holds a segment address. The remaining 
three addresses are all double-word addresses; that is, they are 4 bytes, 
with the offset in the first 2 bytes and the segment address in the last 
2 bytes. 


The Environment Block 


Each program that the EXEC function loads inherits a data structure 
called an environment block from its parent. The pointer to the segment 
of the block is at offset 002CH in the PSP. The environment block holds 
certain information used by the system’s command interpreter (usually 
COMMAND.COM) and may also hold information to be used by transient 
programs. It has no effect on the operation of the operating system 
proper. 


If the environment-block pointer in the EXEC parameter block contains 
zero, the child program acquires a copy of the parent program’s environ- 
ment block. Alternatively, the parent program can provide a segment 
pointer to a different or expanded environment. The maximum size of the 
environment block is 32 KB, so very large chunks of information can be 
passed between programs by this mechanism. 


The environment block for any given program is static, implying that if 
more than one generation of child programs is resident in RAM, each one 
will have a distinct and separate copy of the environment block. Further- 
more, the environment block for a program that terminates and stays resi- 
dent is not updated by subsequent PATH and SET commands. 


You will find more details about the environment block later in this 
chapter. 


The Command Tail 

MS-DOS copies the command tail into the child program’s PSP at offset 
0080H, as described in Chapter 3. The information takes the form of a 
count byte, followed by a string of ASCII characters, terminated by a car- 
riage return; the carriage return is not included in the count. 
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The command tail can include filenames, switches, or other parameters. 
From the child program’s point of view, the command tail should provide 
the same information that would be present if the program had been run 
by a direct user command at the MS-DOS prompt. EXEC ignores any I/O- 
redirection parameters placed in the command tail; the parent program 
must provide for redirection of the standard devices before the EXEC 
call is made. | 


The Default File Control Blocks : 


MS-DOS copies the two default file control blocks pointed to by the EXEC 
parameter block into the child program's PSP at offsets 005CH and 006CH. 
To emulate the function of COMMAND.COM from the child program’s 
point of view, the parent program should use Int 21H Function 29H 
(the system parse-filename service) to parse the first two parameters of 
the command tail into the default file control blocks before invoking the 
EXEC function. 


File control blocks are not much use under MS-DOS versions 2 and 3, 
because they do not support the hierarchical file structure, but some ap- 
plication programs do inspect them as a quick way to get at the first two 
switches or other parameters in the command tail. Chapter 8 discusses file 
control blocks in more detail. 


Returning from the EXEC Function 


In MS-DOS version 2, the EXEC function destroys the contents of all regis- 
ters except the code segment (CS) and instruction pointer (IP). Therefore, 
before making the EXEC call, the parent program must push the contents 
of any other registers that are important onto the stack and then save the 
stack segment (SS) and stack pointer (SP) registers in variables. Upon 
return from a successful EXEC call (that is, the child program has finished 
executing), the parent program should reload SS and SP from the variables 
where they were saved and then pop the other saved registers off the 
stack. In MS-DOS versions 3.0 and later, the stack and other registers are 
preserved across the EXEC call in the usual fashion. 


Finally, the parent can use Int 21H Function 4DH to obtain the termination 
type and return code of the child program. 


The EXEC function will fail under the following conditions: 


= Not enough unallocated memory is available to load and execute the 
requested program file. 


a The requested program can’t be found on the disk. 
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a The transient portion of COMMAND.COM in highest RAM (which 
contains the actual loader) has been destroyed and not enough free 
memory is available to reload it (PC-DOS version 2 only). 


Figure 12-1 summarizes the calling convention for function 4BH. Figure 
12-2 shows a skeleton of a typical EXEC call. This particular example uses 
the EXEC function to load and run the MS-DOS utility CHKDSK.COM. 
The SHELL.ASM program listing later in this chapter (Figure 12-5) pre- 
sents a more complete example that includes the use of Int 21H Function 
4AH to free unneeded memory. 


Figure 12-1. Calling convention for the EXEC Junction (Int 21H Function 4BH). 
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(continued) 


Figure 12-2. A brief example of the use of the MS-DOS EXEC call, with all necessary 
variables and command blocks. Note the protection of the registers for MS-DOS ver- 
sion 2 and the masking of interrupts during loading of SS:SP to circumvent a bug in 


some early 8088 CPUs. 
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Figure 12-2. continued 


More About the Environment Block 


The environment block is always paragraph aligned (starts at an address 
that is a multiple of 16 bytes) and contains a series of ASCIIZ strings. Each 
of the strings takes the following form: 


NAME=PARAMETER 


An additional zero byte (Figure 12-3) indicates the end of the entire set of 
strings. Under MS-DOS version 3, the block of environment strings and the 
extra zero byte are followed by a word count and the complete drive, 
path, filename, and extension used by EXEC to load the program. 


Figure 12-3. Dump of a typical environment block under MS-DOS version 3. This 
particular example contains the default COMSPEC parameter and two relatively 
complex PATH and PROMPT control strings that were set up by entries in the user's 
AUTOEXEC file. Note the path and file specification of the executing program fSollow- 
ing the double zeros at offset 0073H that denote the end of the environment block. 
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Under normal conditions, the environment block inherited by a program 
will contain at least three strings: 


COMSPEC=evariable 
PAT H=variable 
PROMPT=variable 


MS-DOS places these three strings into the environment block at system 
initialization, during the interpretation of SHELL, PATH, and PROMPT 
directives in the CONFIG.SYS and AUTOEXEC.BAT files. The strings tell 
the MS-DOS command interpreter, COMMAND.COM, the location of its 
executable file (to enable it to reload the transient portion), where to 
search for executable external commands or program files, and the format 
of the user prompt. 


You can add other strings to the environment block, either interactively or 
in batch files, with the SET command. Transient programs can use these 
strings for informational purposes. For example, the Microsoft C Compiler 
looks in the environment block for INCLUDE, LIB, and TMP strings to tell 
it where to find its #include files and library files and where to build its 
temporary working files. 


Example Programs: SHELL.C and SHELL.ASM 


As a practical example of use of the MS-DOS EXEC function, | have 
included a small command interpreter called SHELL, with equivalent 
Microsoft C (Figure 12-4) and Microsoft Macro Assembler (Figure 12-5) 
source code. The source code for the assembly-language version is con- 
siderably more complex than the code for the C version, but the names 
and functionality of the various procedures are quite parallel. 


(continued) 


Figure 12-4. SHELL.C: A table-driven command interpreter writien in Microsoft C. 
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Figure 12-4. continued 


(continued) 
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Figure 12-4. continued 
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Figure 12-4. continued 


(continued) 
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Figure 12-4. continued 


(continued) 


Figure 12-5. SHELL.ASM: A simple table-driven command interpreter written in 
Microsoft Macro Assembler. 
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Figure 12-5. continued 


(continued) 
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Figure 12-5. continued 


(continued) 
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Figure 12-5. continued 
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Figure 12-5. continued 
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Figure 12-5. continued 
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The SHELL program is table driven and can easily be extended to provide 
a powerful customized user interface for almost any application. When 
SHELL takes control of the system, it displays the prompt 


sh: 


and waits for input from the user. After the user types a line terminated 
by a carriage return, SHELL tries to match the first token in the line against 
its table of internal Gintrinsic) commands. If it finds a match, it calls the 
appropriate subroutine. If it does not find a match, it calls the MS-DOS 
EXEC function and passes the user’s input to COMMAND.COM with the 
/C switch, essentially using COMMAND.COM as a transient command 
processor under its own control. 


As supplied in these listings, SHEZZ “knows” exactly three internal 
commands: 


Command Action 

CLS Uses the ANSI standard control sequence to clear the display 
screen and home the cursor. 

DOS Runs a copy of COMMAND.COM. 

EXIT Exits SHELL, returning control of the system to the next lower 
command interpreter. 


You can quickly add new intrinsic commands to either the C version or the 
assembly-language version of SHELL. Simply code a procedure with the 
appropriate action and insert the name of that procedure, along with the 
text string that defines the command, into the table COMMANDS. In 
addition, you can easily prevent SHELL from passing certain “dangerous” 
commands (such as MKDIR or ERASE) to COMMAND.COM simply by 
putting the names of the commands to be screened out into the intrinsic 
command table with the address of a subroutine that prints an error 
message. 


To summarize, the basic flow of both versions of the SHELL program is 
as follows: 


1. The program calls MS-DOS Int 21H Function 4AH (Resize Memory 
Block) to shrink its memory allocation, so that the maximum possible 
space will be available for COMMAND.COM if it is run as an overlay. 
(This is explicit in the assembly-language version only. To keep the ex- 
ample code simple, the number of paragraphs to be reserved is coded 
as a generous literal value, rather than being figured out at runtime 
from the size and location of the various program segments.) 
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2. The program searches the environment for the COMSPEC variable, 
which defines the location of an executable copy of COMMAND.COM. 
If it can’t find the COMSPEC variable, it prints an error message and 
exits. 


3. The program puts the address of its own handler in the Ctrl-C vector 
(Int 23H) so that it won't lose control if the user enters a Ctrl-C or 
a Ctrl-Break. 


4, The program issues a prompt to the standard output device. 


5. The program reads a buffered line from the standard input device to 
get the user’s command. 


6. The program matches the first blank-delimited token in the line 
against its table of intrinsic commands. If it finds a match, it executes 
the associated procedure. 


7. If the program does not find a match in the table of intrinsic com- 
mands, it synthesizes a command-line tail by appending the user’s 
input to the /C switch and then EXECs a copy of COMMAND.COM, 
passing the address of the synthesized command tail in the EXEC 
parameter block. 


8. The program repeats steps 4 through 7 until the user enters the com- 
mand EXIT, which is one of the intrinsic commands, and which causes 
SHELL to terminate execution. 


In its present form, SHELL allows COMMAND.COM to inherit a full copy 
of the current environment. However, in some applications it may be 
helpful, or safer, to pass a modified copy of the environment block so that 
the secondary copy of COMMAND.COM will not have access to certain 
information. 


Using EXEC to Load Overlays 


Loading overlays with the EXEC function is much less complex than using 
EXEC to run another program. The overlay can be constructed as either a 
memory image (.COM) or relocatable (.EXE) file and need not be the same 
type as the program that loads it. The main program, called the root seg- 
ment, must carry out the following steps to load and execute an overlay: 


1. Make a memory block available to receive the overlay. The program 
that calls EXEC must own the memory block for the overlay. 
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2. Set up the overlay parameter block to be passed to the EXEC function. 
This block contains the segment address of the block that will receive 
the overlay, plus a segment relocation value to be applied to the con- 
tents of the overlay file if it is a EXE file). These are normally the 
same value. 


3. Call the MS-DOS EXEC function to load the overlay by issuing an Int 
21H with the registers set up as follows: 


AH = 4BH 
AL = 03H (EXEC subfunction to load overlay) 
DS:DX = segment:offset of overlay file pathname 


ES:BX = segment:offset of overlay parameter block 


Upon return from the EXEC function, the carry flag is clear if the over- 
lay was found and loaded. The carry flag is set if the file could not be 
found or if some other error occurred. 


4. Execute the code within the overlay by transferring to it with a far call. 
The overlay should be designed so that either the entry point or a 
pointer to the entry point is at the beginning of the module after it is 
loaded. This technique allows you to maintain the root and overlay 
modules separately, because the root module does not contain any 
“magical” knowledge of addresses within the overlay segment. 


To prevent users from inadvertently running an overlay directly from the 
command line, you should assign overlay files an extension other than 
.COM or .EXE. It is most convenient to relate overlays to their root seg- 
ment by assigning them the same filename but a different extension, such 
as .OVL or .OVI, .OV2, and so on. 


Figure 12-6 shows the use of EXEC to load and execute an overlay. 


(continued) 


Figure 12-6. A code skeleton for loading and executing an overlay with the EXEC 
function. The overlay file may be in either .COM or .EXE format. 
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Figure 12-6. continued 
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Chapter 13 


Interrupt Handlers 


Interrupts are signals that cause the computer’s central processing unit to 
suspend what it is doing and transfer to a program called an interrupt han- 
dler. Special hardware mechanisms that are designed for maximum speed 
force the transfer. The interrupt handler determines the cause of the inter- 
rupt, takes the appropriate action, and then returns control to the original 
process that was suspended. 


Interrupts are typically caused by events external to the central processor 
that require immediate attention, such as the following: 


=" Completion of an I/O operation 
= Detection of a hardware failure 
= “Catastrophes” (power failures, for example) 


In order to service interrupts more efficiently, most modern processors 
support multiple interrupt types, or levels. Each type usually has a 
reserved location in memory, called an interrupt vector, that specifies 
where the interrupt-handler program for that interrupt type is located. 
This design speeds processing of an interrupt because the computer can 
transfer control directly to the appropriate routine; it does not need a 
central routine that wastes precious machine cycles determining the 
cause of the interrupt. The concept of interrupt types also allows inter- 
rupts to be prioritized, so that if several interrupts occur simultaneously, 
the most important one can be processed first. 


CPUs that support interrupts must also have the capability to block inter- 
rupts while they are executing critical sections of code. Sometimes the 
CPU can block interrupt levels selectively, but more frequently the effect is 
global. While an interrupt is being serviced, the CPU masks all other inter- 
rupts of the same or lower priority until the active handler has completed 
its execution; similarly, it can preempt the execution of a handler if a dif- 
ferent interrupt with higher priority requires service. Some CPUs can even 
draw a distinction between selectively masking interrupts (they are 
recognized, but their processing is deferred) and simply disabling them 
(the interrupt is thrown away). 


The creation of interrupt handlers has traditionally been considered one 
of the most arcane of programming tasks, suitable only for the elite cadre 
of system hackers. In reality, writing an interrupt handler is, in itself, 
straightforward. Although the exact procedure must, of course, be cus- 
tomized for the characteristics of the particular CPU and operating sys- 
tem, the guidelines on the following page are applicable to almost any 
computer system. 
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A program preparing to handle interrupts must do the following: 


1. Disable interrupts, if they were previously enabled, to prevent them 
from occurring while interrupt vectors are being modified. 


2. Initialize the vector for the interrupt of interest to point to the pro- 
gram’s interrupt handler. 


3. Ensure that, if interrupts were previously disabled, all other vectors 
point to some valid handler routine. 


4, Enable interrupts again. 


The interrupt handler itself must follow a simple but rigid sequence of 
steps: 


1. Save the system context (registers, flags, and anything else that the 
handler will modify and that wasn’t saved automatically by the CPU). 


2. Block any interrupts that might cause interference if they were allowed 
to occur during this handler’s processing. (This is often done automati- 
cally by the computer hardware.) 


3. Enable any interrupts that should still be allowed to occur during this 
handler’s processing. 


4. Determine the cause of the interrupt. 


5. Take the appropriate action for the interrupt: receive and store data 
from the serial port, set a flag to indicate the completion of a disk- 
sector transfer, and so forth. 


6. Restore the system context. 


7. Reenable any interrupt levels that were blocked during this handler’s 
execution. 


8. Resume execution of the interrupted process. 


As in writing any other program, the key to success in writing an interrupt 
handler is to program defensively and cover all the bases. The main 
reason interrupt handlers have acquired such a mystical reputation is that 
they are so difficult to debug when they contain obscure errors. Because 
interrupts can occur asynchronously —that is, because they can be caused 
by external events without regard to the state of the currently executing 
process—bugs in interrupt handlers can cause the system as a whole to 
behave quite unpredictably. 
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Interrupts and the Intel 80x86 Family 


The Intel 80x86 family of microprocessors supports 256 levels of priori- 
tized interrupts, which can be triggered by three types of events: 


= Internal hardware interrupts 
# External hardware interrupts 


= Software interrupts 


Internal Hardware Interrupts 


Internal hardware interrupts, sometimes called faults, are generated by 
certain events encountered during program execution, such as an attempt 
to divide by zero. The assignment of such events to certain interrupt num- 
bers is wired into the processor and is not modifiable (Figure 13-1). 


Interrupt Vector Interrupt 
level address trigger 8086/88 80286 80386 
00H OOH-03H ___ Divide-by-zero x x x 
01H 04H-07H __ Single step x x x 
02H 08H-OBH  Nonmaskable 

interrupt(NMI) x x x 
03H OCH-OFH  Breakpoint x x x 
04H 10H-13H Overflow x x x 
05H . 14H-17H BOUND exceeded x x 
06H 18H-1BH _Invalid opcode x x 
07H 1CH-1FH Processor extension 

not available x x 
08H 20H-23H Double fault x x 
09H 24H-27H —_ Segment overrun x X 
OAH 28H-2BH Invalid task-state 

segment x x 
0OBH 2CH-2FH Segment not present x x 
0CH 30H-33H Stack segment 

overrun x x 
0ODH 34H-37H General protection 

fault x x 
0EH 38H-3BH __s Page fault x 
OFH 3CH-3FH _ Reserved 
10H 40H-43H Numeric coprocessor 

error x x 
11H-1FH 44H-7FH _ Reserved 


-_—— re a serene 
Figure 13-1. Internal interrupts (faults) on the Intel 8086/88, 80286, and 80386 
microprocessors. 
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External Hardware Interrupts 


External hardware interrupts are triggered by peripheral device con- 
trollers or by coprocessors such as the 8087/80287. These can be tied to ei- 
ther the CPU's nonmaskable-interrupt (NMD) pin or its maskable-interrupt 
(INTR) pin. The NMI line is usually reserved for interrupts caused by such 
catastrophic events as a memory parity error or a power failure. 


Instead of being wired directly to the CPU, the interrupts from external 
devices can be channeled through a device called the Intel 8259A Pro- 
grammable Interrupt Controller (PIC). The CPU controls the PIC through 
a set of I/O ports, and the PIC, in turn, signals the CPU through the INTR 
pin. The PIC allows the interrupts from specific devices to be enabled and 
disabled, and their priorities to be adjusted, under program control. 


A single PIC can handle only eight levels of interrupts. However, PICs can 
be cascaded together in a treelike structure to handle as many levels as 
desired. For example, 80286- and 80386-based machines with a PC/AT- 
compatible architecture use two PICs wired together to obtain 16 indi- 
vidually configurable levels of interrupts. 


INTR interrupts can be globally enabled and disabled with the CPU's STI 
and CLI instructions. As you would expect, these instructions have no 
effect on interrupts received on the CPU’s NMI pin. 


The manufacturer of the computer system and/or the manufacturer of the 
peripheral device assigns external devices to specific 8259A PIC interrupt 
levels. These assignments are realized as physical electrical connections 
and cannot be modified by software. 


Software Interrupts 


Any program can trigger software interrupts synchronously simply by 
executing an INT instruction. MS-DOS uses Interrupts 20H through 3FH 
to communicate with its modules and with application programs. (For 
instance, the MS-DOS function dispatcher is reached by executing an Int 
21H.) The IBM PC ROM BIOS and application software use other inter- 
rupts, with either higher or lower numbers, for various purposes (Figure 
13-2). These assignments are simply conventions and are not wired into 
the hardware in any way. 
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Interrupt Usage Machine 
00H Divide-by-zero PG, AT, PS/2 
01H Single step PC, AT, PS/2 
02H NMI PC, AT, PS/2 
03H Breakpoint PC, AT, PS/2 
04H Overflow PC, AT, PS/2 
05H ROM BIOS PrintScreen PC, AT, PS/2 
BOUND exceeded AT, PS/2 
06H Reserved PC 
Invalid opcode AT, PS/2 
07H Reserved PC 
80287/80387 not present AT, PS/2 
08H IRQO timer tick PC, AT, PS/2 
Double fault AT, PS/2 
09H IRQ1 keyboard PC, AT, PS/2 
80287/80387 segment overrun AT, PS/2 
OAH IRQ2 reserved PC 
IRQ2 cascade from slave 8259A PIC AT, PS/2 
Invalid task-state segment (TSS) AT, PS/2 
OBH IRQ3 serial communications (COM2) PC, AT, PS/2 
Segment not present AT, PS/2 
OCH IRQ4 serial communications (COM1) PC, AT, PS/2 
Stack segment overflow AT, PS/2 
0ODH IRQ5 fixed disk PC 
IRQ5 parallel printer (LPT2) AT 
Reserved PS/2 
General protection fault AT, PS/2 
0EH IRQ6 floppy disk PC, AT, PS/2 
Page fault AT, PS/2 
OFH IRQ7 parallel printer (LPT1) PC, AT, PS/2 
10H ROM BIOS video driver PC, AT, PS/2 
Numeric coprocessor fault AT, PS/2 
11H ROM BIOS equipment check PC, AT, PS/2 
12H ROM BIOS conventional-memory size PC, AT, PS/2 
13H ROM BIOS disk driver PC, AT, PS/2 
14H ROM BIOS communications driver PC, AT, PS/2 
15H ROM BIOS cassette driver PC 
ROM BIOS I/O system extensions AT, PS/2 
16H ROM BIOS keyboard driver PC, AT, PS/2 
17H ROM BIOS printer driver PC, AT, PS/2 
18H ROM BASIC PC, AT, PS/2 
19H ROM BIOS bootstrap PC, AT, PS/2 
a 
(continued) 


Figure 13-2. Interrupts with special significance on the IBM PC, PC/AT. and PS/2 
and compatible computers. Note that the IBM ROM BIOS uses several interrupts in the 
range OOH—IFH, even though they were reserved by Intel for CPU faults. IRQ numbers 
refer to Intel 8259A PIC priority levels. 
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Figure 13-2. continued 
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Interrupt Usage 


1AH 


clea) sata ai em SEE 
ROM BIOS time of day 


1BH 
1CH 
1DH 
1EH 
1FH 
20H 
21H 
22H 
23H 
24H 
25H 
26H 
27H 
28H 
29H 
2AH 
2BH-2EH 
2FH 
30H-3FH 
40H 
41H 


42H 
43H 
44H 
46H 
4AH 
5AH 
5BH 
60H-—66H 
67H 
68H-6FH 
70H 
71H 
72H 
73H 
74H 


75H 
76H 
77H 
78H-7FH 
80H-—FOH 
F1H-FFH 


ROM BIOS Ctrl-Break 

ROM BIOS timer tick 

ROM BIOS video parameter table 
ROM BIOS floppy-disk parameters 
ROM BIOS font (characters 80H-FFH) 
MS-DOS terminate process 

MS-DOS function dispatcher 

MS-DOS terminate address 

MS-DOS Ctrl-C handler address 
MS-DOS critical-error handler address 
MS-DOS absolute disk read 

MS-DOS absolute disk write 

MS-DOS terminate and stay resident 
MS-DOS idle interrupt 

MS-DOS reserved 

MS-DOS network redirector 

MS-DOS reserved 

MS-DOS multiplex interrupt 

MS-DOS reserved 

ROM BIOS floppy-disk driver (if fixed disk installed) 
ROM BIOS fixed-disk parameters 
ROM BIOS fixed-disk parameters (drive 0) 
ROM BIOS default video driver Gif EGA installed) 
EGA, MCGA, VGA character table 
ROM BIOS font (characters OOH—7FH) 
ROM BIOS fixed-disk parameters (drive 1) 
ROM BIOS alarm handler 

Cluster adapter 

Used by cluster program 

User interrupts 

LIM EMS driver 

Unassigned. 

IRQ8 CMOS real-time clock 

IRQ9Y software diverted to IRQ2 
IRQ10 reserved 

IRQ11 reserved 

IRQ12 reserved 

IRQ12 mouse 

TRQ13 numeric coprocessor 

IRQ14 fixed-disk controller 

IRQ15 reserved 

Unassigned 

BASIC 

Not used 


Machine 


AT, PS/2 

PC, AT, PS/2 
PC, AT, PS/2 
PC, AT, PS/2 
PC, AT, PS/2 
PC, AT, PS/2 


PC, AT, PS/2 
PC 

AT, PS/2 
PC, AT, PS/2 
PC, AT, PS/2 
PCjr 

AT, PS/2 

AT, PS/2 
PC, AT 

PC, AT 

PC, AT, PS/2 
PC, AT, PS/2 


AT, PS/2 
AT, PS/2 
AT, PS/2 
AT, PS/2 
AT 

PS/2 

AT, PS/2 
AT, PS/2 
AT, PS/2 


PC, AT, PS/2 
PC, AT, PS/2 
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The Interrupt-Vector Table 

The bottom 1024 bytes of system memory are called the interrupt-vector 
table. Each 4-byte position in the table corresponds to an interrupt type (0 
through OFFH) and contains the segment and offset of the interrupt han- 
dler for that level. Interrupts 0 through 1FH (the lowest levels) are used for 
internal hardware interrupts; MS-DOS uses Interrupts 20H through 3FH; 
all the other interrupts are available for use by either external hardware 
devices or system drivers and application software. 


When an 8259A PIC or other device interrupts the CPU by means of the 
INTR pin, it must also place the interrupt type as an 8-bit number (0 
through OFFH) on the system bus, where the CPU can find it. The CPU 
then multiplies this number by 4 to find the memory address of the inter- 
rupt vector to be used. 


Servicing an Interrupt 
When the CPU senses an interrupt, it pushes the program status word 
(which defines the various CPU flags), the code segment (CS) register, and 
the instruction pointer (IP) onto the machine stack and disables the inter- 
rupt system. It then uses the 8-bit number that was jammed onto the sys- 
tem bus by the interrupting device to fetch the address of the handler from 
the vector table and resumes execution at that address. 


Usually the handler immediately reenables the interrupt system (to allow 
higher-priority interrupts to occur), saves any registers it is going to use, 
and then processes the interrupt as quickly as possible. Some external 
devices also require a special acknowledgment signal so that they will 
know the interrupt has been recognized. 


If the interrupt was funneled through an 8259A PIC, the handler must send 
a special code called end of interrupt (EOD to the PIC through its control 
port to tell it when interrupt processing is completed. (The EOI has no 
effect on the CPU itself.) Finally, the handler executes the special IRET 
(INTERRUPT RETURN) instruction that restores the Original state of the 
CPU flags, the CS register, and the instruction pointer (Figure 13-3). 


Whether an interrupt was triggered by an external device or forced by 
software execution of an INT instruction, there is no discernible differ- 
ence in the system state at the time the interrupt handler receives control. 
This fact is convenient when you are writing and testing external interrupt 
handlers because you can debug them to a large extent simply by invoking 
them with software drivers. 
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Figure 13-3. Typical handler for hardware interrupts on the 80x86 family of micro- 
processors. In real life, the interrupt handler would need to save and restore only the 
registers that it actually modified. Also, if the handler made extensive use of the ma- 
chine stack, it would need to save and restore the SS and SP registers of the interrupted 
process and use its own local stack. 
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Interrupt Handlers and MS-DOS 


The introduction of an interrupt handler into your program brings with it 
considerable hardware dependence. It goes without saying (but I am say- 
ing it again here anyway) that you should avoid such hardware depen- 
dence in MS-DOS applications whenever possible, to ensure that your 
programs will be portable to any machine running current versions of 
MS-DOS and that they will run properly under future versions of the 
operating system. 


Valid reasons do exist, however, for writing your own interrupt handler for 
use under MS-DOS: 


u To supersede the MS-DOS default handler for an internal hardware in- 
terrupt (such as divide-by-zero, BOUND exceeded, and so forth). 


= To supersede the MS-DOS default handler for a defined system excep- 
tion, such as the critical-error handler or Ctrl-C handler. 


= To chain your own interrupt handler onto the default system handler 
for a hardware device, so that both the system's actions and your own 
will occur on an interrupt. (A typical example of this is the “clock-tick” 
interrupt.) 


= To service interrupts not supported by the default MS-DOS device 
drivers (such as the serial communications port, which can be used at 
much higher speeds with interrupts than with polling). 


= To provide a path of communication between a program that termi- 
nates and stays resident and other application software. 


MS-DOS provides the following facilities to enable you to install well- 
behaved interrupt handlers in a manner that does not interfere with 
operating-system functions or other interrupt handlers: 


Ss 


Function Action 

Int 21H Function 25H Set interrupt vector. 

Int 21H Function 35H Get interrupt vector. 

Int 21H Function 31H Terminate and stay resident. 


These functions allow you to examine or modify the contents of the sys- 
tem interrupt-vector table and to reserve memory for the use of a handler 
without running afoul of other processes in the system or causing memory 
use conflicts. Section II of this book, “MS-DOS Functions Reference,” 
describes each of these functions in detail, with programming examples. 
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Handlers for external hardware interrupts under MS-DOS must operate 
_ under some fairly severe restrictions: 


Because the current versions of MS-DOS are not reentrant, a hardware 
interrupt handler should never call the MS-DOS functions during the 
actual interrupt processing. 


The handler must reenable interrupts as soon as it gets control, to 
avoid crippling other devices or destroying the accuracy of the system 
clock. 


A program should access the 8259A PIC with great care. The program 
should not access the PIC unless that program is known to be the only 
process in the system concerned with that particular interrupt level. 
And it is vital that the handler issue an end-of-interrupt code to the 
8259A PIC before performing the IRET; otherwise, the processing of 
further interrupts for that priority level or lower priority levels will be 
blocked. 


Restrictions on handlers that replace the MS-DOS default handlers for in- 
ternal hardware interrupts or system exceptions (such as Ctrl-C or critical 
errors) are not quite so stringent, but you must still program the handlers 
with extreme care to avoid destroying system tables or leaving the operat- 
ing system in an unstable state. 


The following are a few rules to keep in mind when you are writing an 
interrupt driver: 


Use Int 21H Function 25H (Set Interrupt Vector) to modify the interrupt 
vector; do not write directly to the interrupt-vector table. 


If your program is not the only process in the system that uses this in- 
terrupt level, chain back to the previous handler after performing your 
own processing on an interrupt. 


If your program is not going to stay resident, fetch and save the current 
contents of the interrupt vector before modifying it and then restore 
the original contents when your program exits. 


If your program is going to stay resident, use one of the terminate-and- 
stay-resident functions (preferably Int 21H Function 31H) to reserve 
the proper amount of memory for your handler. 


If you are going to process hardware interrupts, keep the time that in- 
terrupts are disabled and the total length of the service routine to an 
absolute minimum. Remember that even after interrupts are reenabled 
with an STI instruction, interrupts of the same or lower priority remain 
blocked if the interrupt was received through the 8259A PIC. 
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ZERODIV, an Example Interrupt Handler 


The listing ZERODIV.ASM (Figure 13-4) illustrates some of the principles 
and guidelines on the previous pages. It is an interrupt handler for the 
divide-by-zero internal interrupt (type 0). ZERODIV is loaded as a .COM 
file (usually by a command in the system’s AUTOEXEC file) but makes it- 
self permanently resident in memory as long as the system is running. 


The ZERODIV program has two major portions: the initialization portion 
and the interrupt handler. 


The initialization procedure (called init in the program listing) is exe- 
cuted only once, when the ZERODIV program is executed from the MS- 
DOS level. The init procedure takes over the type 0 interrupt vector, 
prints a sign-on message, then performs a terminate-and-stay-resident 
exit to MS-DOS. This special exit reserves the memory occupied by the 
ZERODIV program, so that it is not overwritten by subsequent application 
programs. 


The interrupt handler (called zdiv in the program listing) receives control 
when a divide-by-zero interrupt occurs. The handler preserves all regis- 
ters and then prints a message to the user asking whether to continue or to 
abort the program. We can use the MS-DOS console I/O functions within 
this particular interrupt handler because we can safely presume that the 
application was in control when the interrupt occurred; thus, there should 
be no chance of accidentally making overlapping calls upon the operat- 
ing system. 


If the user enters a C to continue, the handler simply restores all the regis- 
ters and performs an IRET (INTERRUPT RETURN) to return control to 
the application. (Of course, the results of the divide operation will be use- 
less.) If the user enters Q to quit, the handler exits to MS-DOS. Int 21H 
Function 4CH is particularly convenient in this case because it allows the 
program to pass a return code and at the same time is the only termina- 
tion function that does not rely on the contents of any of the segment 
registers. 


For an example of an interrupt handler for external (communications port) 
interrupts, see the ZALK terminal-emulator program in Chapter 7. You 
may also want to look again at the discussions of Ctrl-C and critical-error 
exception handlers in Chapters 5 and 8. 
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Figure 13-4. A simple example of an interrrupt handler for use within the MS-DOS 
environment. ZERODIV makes itself permanently resident in memory and handles 
the CPU's internal divide-by-zero interrupt. 
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Figure 13-4. continued 
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Figure 13-4. continued 
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Chapter 14 


Installable Device Drivers 


Device drivers are the modules of an operating system that control the 
hardware. They isolate the operating-system kernel from the specific 
characteristics and idiosyncrasies of the peripheral devices interfaced to 
the central processor. Thus, the driver’s relationship to the kernel is analo- 
gous to the operating system’s relationship to application programs. 


The installable device drivers that were introduced in MS-DOS version 2 
give the user great flexibility. They allow the user to customize and con- 
figure the computer for a wide range of peripheral devices, with a 
minimum of troublesome interactions and without having to “patch” the 
operating system. Even the most inexperienced user can install a new 
device into a system by plugging in a card, copying a driver file to the boot 
disk, and editing the system configuration file. 


For those inclined to do their own programming, the MS-DOS installable 
device drivers are interfaced to the hardware-independent kernel through 
a simple and clearly defined scheme of function codes and data struc- 
tures. Given adequate information about the hardware, any competent 
assembly-language programmer can expect to successfully interface even 
the most bizarre device to MS-DOS without altering the operating sys- 
tem in the slightest and without acquiring any special or proprietary 
knowledge about its innards. 


In retrospect, installable device drivers have proven to be one of the key 
usability features of MS-DOS. I feel that they have been largely responsible 
for the rapid proliferation and competitive pricing of high-speed mass- 
storage devices for MS-DOS machines, and for the growing confidence of 
the average user toward “tampering with” (upgrading) his or her machine. 


MS-DOS Device-Driver Types 


Drivers written for MS-DOS fall into two distinct classes: 
= Block-device drivers 
m Character-device drivers 


A driver’s class determines what functions it must support, how it is 
viewed by MS-DOS, and how it makes the associated physical device ap- 
pear to behave when an application program makes a request for I/O. 
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Character-Device Drivers 


Character-device drivers control peripheral devices that perform input 
and output one character (or byte) at a time, such as a terminal or printer. 
A single character-device driver ordinarily supports a single hardware 
unit. Each character device has a one-to-eight-character logical name, and 
an application program can use this name to open the device for input or 
output, as though it were a file. The logical name is strictly a means of 
identification for MS-DOS and has no physical equivalent on the device. 


MS-DOS’s built-in character-device drivers for the console, serial port, 
and printer are unique in that an application program can access them in 
three different ways: 


= It can open them by name (CON, AUX, PRN, etc.) for input and output, 
like any other character device. 


= It can use the special-purpose MS-DOS function calls (int 21H Func- 
tions 01—OCH). 


= It can use the default handles (standard input, standard output, stan- 
dard error, standard auxiliary, and standard printer), which do not 
need to be opened to be used. 


The number of additional character-device drivers that can be installed is 
limited only by available memory and by the requirement that each driver 
have a unique logical name. If more than one driver uses the same logical 
name, the last driver to be loaded will supersede any others and will 
receive all I/O requests addressed to that logical name. This fact can occa- 
sionally be turned to advantage; for example, it allows the user to replace 
the system’s default CON driver, which does not support cursor position- 
ing or character attributes, with the more powerful ANSLSYS driver. 


ASCII vs Binary Mode 

MS-DOS regards a handle associated with a character device to be in ei- 

ther ASCII (cooked) mode or binary (raw) mode. The mode affects MS- 

DOS’s buffering of data for read and write requests. The driver itself is not 

aware of the mode, and the mode does not affect its operation. An appli- 
cation can select the mode of a handle with the IOCTL function Cnt 21H 

- Function 44H). 


During ASCII-mode input, MS-DOS requests characters one at a time from 
the driver and places them into its own internal buffer, echoing each to the 
screen (if the input device is the keyboard) and checking each character 
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for a Ctrl-C (03H). When the number of characters requested by the appli- 
cation program has been received, when a Ctrl-Z is detected, or when the 
Enter key is pressed (in the case of the keyboard), MS-DOS terminates the 
input and copies the data from its internal buffer into the requesting pro- 
gram’s buffer. Similarly, during ASCII-mode output, MS-DOS passes the 
characters to the device driver one at a time and checks for a Ctrl-C pend- 
ing at the keyboard between each character. When a Ctrl-C is detected, 
MS-DOS aborts the input or output operation and transfers to the routine 
whose address is stored in the Int 23H vector. 


In binary mode, MS-DOS reads or writes the exact number of bytes re- 
quested by the application program, without regard to any control charac- 
ters such as Enter or Ctrl-C. MS-DOS passes the entire request through to 
the driver in a single operation, instead of breaking it into single-character 
reads or writes, and transfers the characters directly to or from the re- 
questing program’s buffer. 


Block-Device drivers 


Block-device drivers usually control random-access mass-storage devices 
such as floppy-disk drives and fixed disks, although they can also be used 
to control non-random-access devices such as magnetic-tape drives. 
Block devices transfer data in chunks, rather than one byte at a time. The 
size of the blocks may be either fixed (disk drives) or variable (tape 
drives). 


A block driver can support more than one hardware unit, map a single 
physical unit onto two or more logical units, or both. Block devices do not 
have file-like logical names, as character devices do. Instead, MS-DOS 
assigns drive designators to the block-device units or logical drives in an 
alphabetic sequence: A, B, and so forth. Each logical drive contains a file 
system: boot block, file allocation table, root directory, and so forth. (See 
Chapter 10.) 


A block-device driver’s position in the chain of all drivers determines the 
first letter assigned to that driver. The number of logical drive units that 
the driver supports determines the total number of letters assigned to it. 


Block-device drivers always read or write exactly the number of sectors 
requested (barring hardware or addressing errors) and never filter or 
otherwise manipulate the contents of the blocks being transferred. 


Programming for MS-DOS 


Structure of am MS-DOS Device Driver 
A device driver consists of three major parts (Figure 14-1): 
a A device header 
= A strategy (strat) routine 
= An interrupt (intr) routine 


We'll discuss each of these in more detail as we work through this chapter. 
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Figure 14-1. General structure of an MS-DOS installable device driver. 


The Device Header 


The device header (Figure 14-2) lies at the beginning of the driver. It con- 
tains a link to the next driver in the chain, a set of attribute flags for the 
device (Figure 14-3), offsets to the executable strategy and interrupt rou- 
tines for the device, and the logical-device name Cif it is a character device 
such as PRN or COMI) or the number of logical units Gif it is a block 
device). 
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Byte offset 


OOH 
02H 
04H 
06H 
08H 
OAH 
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Figure 14-2. Device-driver header. The offsets to the strat and intr routines are off- 
sets from the same segment used to point to the device header. 


Bit 


15 
14 
13 


Significance 


1 if character device, 0 if block device 

1 if IOCTL read and write supported 

for block devices: 

1 if BIOS parameter block in boot sector should be used to determine media 
characteristics, 0 if media ID byte should be used 

for character devices: 

1 if output until busy supported 

Reserved (should be 0) 

1 if open/close/removable media supported (MS-DOS 3.0 and later) 

Reserved (should be 0) 

1 if generic IOCTL and get/set logical drive supported (MS-DOS 3.2 and 
later) 

Reserved (should be 0) 

1 if CON driver and Int 29H fast-output function supported 

1 if current CLOCK$ device 

1 if current NUL device 

for block devices: 

1 if driver supports 32-bit sector addressing (MS-DOS 4.0) 

for character devices: 

1 if standard output device (stdout) 

1 if current standard input device (stdin) 


TT ---- rr SSS 


Figure 14-3. Device attribute word in device header. In block-device drivers, only 
bits 6, 11, and 13-15 (and bit 1 in MS-DOS version 4.0) have significance; the 
remainder should always be zero. 
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The Strategy Routine 


MS-DOS calls the strategy routine (strat) for the device when the driver is 
first loaded and installed, and again whenever an application program 
issues an I/O request for the device. MS-DOS passes the strategy routine a 
double-word pointer to a data structure called a request header. This 
structure contains information about the type of operation to be per- 
formed. In current versions of MS-DOS, the strategy routine never actually 
performs any I/O operation but simply saves the pointer to the request 
header. The strat routine must not make any Int 21H function calls. 


The first 13 bytes of the request header are the same for all device-driver 
functions and are therefore referred to as the static portion of the header. 
The number and contents of the subsequent bytes vary according to the 
type of function being requested (Figure 14-4). Both MS-DOS and the 
driver read and write information in the request header. 


The request header’s most important component is a command code, or 
function number, passed in its third byte to select a driver subfunction 
such as read, write, or status. Other information passed to the driver in the 
header includes unit numbers, transfer addresses, and sector or byte 
counts. 


Figure 14-4. Format of request header. Only the first 13 bytes are common to all 
driver functions; the number and definition of the subsequent bytes vary, depending 
upon the function type. The structure shown here is the one used by the read and 
write subfunctions of the driver. 
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The Interrupt Routine 


The last and most complex part of a device driver is the interrupt routine 
(intr), which MS-DOS calls immediately after it calls the strategy routine. 
The interrupt routine implements the device driver proper; it performs (or 
calls other resident routines to perform) the actual input or output opera- 
tions, based on the information passed in the request header. The strat 
routine may not make any Int 21H function calls, except for a restricted set 
during-driver initialization. 


When an I/O function is completed, the interrupt routine uses the status 
field in the request header to inform the DOS kernel about the outcome of 
the requested I/O operation. It can use other fields in the request header 
to pass back such useful information as counts of the actual sectors or 
bytes transferred. 


The interrupt routine usually consists of the following elements: 


= A collection of subroutines to implement the various function types 
that may be requested by MS-DOS (sometimes called the command- 
code routines) 


= A centralized entry point that saves all affected registers, extracts the 
desired function code from the request header, and branches to the 
appropriate command-code routine (typically accomplished with a 
jump table) 

=" Acentralized exit point that stores status and error codes into the re- 
quest header (Figures 14-5 and 14-6) and restores the previous contents 
of the affected registers 


The command-code routines that implement the various functions sup- 
ported by an installable device driver are discussed in detail in the follow- 


ing pages. 


Bit(s) Significance 


15 Error 
12-14 Reserved 
9 Busy 
8 Done 


0-7 Error code if bit 15 = 1 


Figure 14-5. Values for the return status word of the request header. 
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Code Meaning 

0 Write-protect violation 

1 Unknown unit 

2 Drive not ready 

3 Unknown command 

4 Data error (CRC) 

5 Bad request-structure length 
6 Seek error 

7 Unknown medium 

8 Sector not found 

9 Printer out of paper 

OAH Write fault 

OBH Read fault 

0CH General failure 

OD-OEH Reserved 

OFH Invalid disk change (MS-DOS versions 3.0 and later) 


Figure 14-6. Driver error codes returned in bits 0 through 7 of the return status 
word of the request header. 


Although its name suggests otherwise, the interrupt routine is never en- 
tered asynchronously (on an I/O completion interrupt, for example). 
Thus, the division of function between strategy and interrupt routines is 
completely artificial in the current versions of MS-DOS. 


The Command-Code Routines 


A total of 20 command codes are defined for MS-DOS device drivers. The 
command codes (which are not consecutive), the names of the associated 
driver-interrupt routines, and the MS-DOS versions in which they are first 
supported are as follows: 


Command Character Block MS-DOS 
code Function driver driver version 
0 Init Cinitialization) »4 x 2.0 
1 Media Check X 2.0 
2 Build BPB X 2.0 
3 IOCTL Read xX X 2.0 
4 Read X xX 2.0 
5 Nondestructive Read X 2.0 
6 Input Status xX 2.0 
7 Flush Input Buffers X 2.0 
8 Write X X 2.0 
(continued) 
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Command Character Block MS-DOS 

code Function driver driver version 
9 Write with Verify X 2.0 

10 Output Status xX 2.0 

11 Flush Output Buffers X 2.0 

12 IOCTL Write X xX 2.0 

13 Device Open Xx x 3.0 

14 Device Close X X 3.0 

15 Removable Media X 3.0 

16 Output Until Busy X 3.0 

19 Generic IOCTL X -X 3.2 

23 Get Logical Device xX 3.2 

24 Set Logical Device X 3.2 


As you can see from the preceding table, a driver’s interrupt section must 
support functions 0 through 12 under all versions of MS-DOS. Drivers 
tailored for MS-DOS 3.0 and 3.1 can optionally support an additional four 
functions, and MS-DOS drivers for versions 3.2 and later can support three 
more (for a total of 20). MS-DOS inspects the bits in the attribute word of 
the device-driver header to determine which of the optional functions a 
driver supports, if any. 


Some of the functions are relevant only for character-device drivers and 
some only for block-device drivers; a few have meaning to both types. In 
any case, both driver types should have an executable routine present for 
each function, even if it does nothing except set the done flag in the status 
word of the request header. 


In the command-code descriptions that follow, RH refers to the request 
header whose address was passed to the strategy routine in ES:BX, BYTE 
is an 8-bit parameter, WORD is a 16-bit parameter, and DWORD is a far 
pointer (a 16-bit offset followed by a 16-bit segment). 


Function 00H (0): Driver Initialization 


MS-DOS requests the driver's initialization function (init) only once, 
when the driver is first loaded. This function performs any necessary 
device hardware initialization, setup of interrupt vectors, and so forth. The 
initialization routine must return the address of the position where free 
memory begins after the driver code (the break address), so that MS-DOS 
knows where it can build certain control structures and then load the next 
installable driver. If this is a block-device driver, init must also return the 
number of units and the address of a BPB pointer array. 


268 = Programming for MS-DOS 


MS-DOS uses the number of units returned by a block driver in the 
request header to assign drive identifiers. For example, if the current maxi- 
mum drive is D and the driver being initialized supports four units, MS- 
DOS will assign it the drive letters E, F, G, and H. Although the device- 
driver header also has a field for number of units, MS-DOS does not 
inspect it. 


The BPB pointer array is an array of word offsets to BIOS parameter 
blocks (Figure 14-7). Each unit defined by the driver must have one entry 
in the array, although the entries can all point to the same BPB to conserve 
memory. During the operating-system boot sequence, MS-DOS scans all 
the BPBs defined by all the units in all the block-device drivers to deter- 
mine the largest sector size that exists on any device in the system and 
uses this information to set its cache buffer size. 


The operating-system services that the initialization code can invoke at 
load time are very limited—only Int 21H Functions 01H through OCH and 
30H. These are just adequate to check the MS-DOS version number and 
display a driver-identification or error message. 


Many programmers position the initialization code at the end of the driver 
and return that address as the location of the first free memory, so that MS- 
DOS will reclaim the memory occupied by the initialization routine after 
the routine is finished with its work. If the initialization routine finds that 
the device is missing or defective and wants to abort the installation of the 
driver completely so that it does not occupy any memory, it should return 


Byte(s) Contents 

00-—01H Bytes per sector 

02H Sectors per allocation unit (power of 2) 

03H-04H Number of reserved sectors (starting at sector 0) 

05H Number of file allocation tables 

06H-07H Maximum number of root-directory entries 

O8H-—09H Total number of sectors in medium 

OAH Media descriptor byte 

OBH-OCH Number of sectors occupied by a single FAT 

ODH-OEH _ Sectors per track (versions 3.0 and later) 

OFH-10H Number of heads (versions 3.0 and later) 

11H-12H Number of hidden sectors (versions 3.0 and later) 
13H-14H  High-order word of number of hidden sectors (version 4.0) 
15H-18H _ If bytes 8-9 are zero, total number of sectors in medium (version 4.0) 
19H-1EH Reserved, should be zero (version 4.0) 


Figure 14-7. Structure of a BIOS parameter block (BPB). Every formatted disk 
contains a copy of its BPB in the boot sector. (See Chapter 10.) 
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number of units as zero and set the free memory address to CS:0000H. (A 
character-device driver that wants to abort its installation should clear bit 
15 of the attribute word in the driver header and then set the units field 
and free memory address as though it were a block-device driver.) 


The initialization function is called with 


RH +2 BYTE Command code = 0 

RH + 18 DWORD Pointer to character after equal sign on CONFIG.SYS line 
that loaded driver (this information is read-only) 

RH + 22 BYTE Drive number for first unit of this block driver (0 = A, 1 = B, 
and so forth) (MS-DOS version 3 only) 


It returns: 


RH + 3 WORD Status 

RH + 13 BYTE Number of units (block devices only) 

RH + 14 DWORD _ Address of first free memory above driver (break address) 
RH + 18 DWORD _ BPB pointer array (block devices only) 


Function 01H (1): Media Check 
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The media-check function applies only to block devices, and in character- 
device drivers it should do nothing except set the done flag. This function 
is called when a drive-access call other than a simple file read or write is 
pending. MS-DOS passes to the function the media descriptor byte for the 
disk that it assumes is in the drive (Figure 14-8). If feasible, the media- 
check routine returns a code indicating whether the disk has been 
changed since the last transfer. If the media-check routine can assert that 
the disk has not been changed, MS-DOS can bypass rereading the FAT 
before a directory access, which improves overall performance. 


I IE aE NE a ET) 
Code Meaning 


OFOH 3.5", 2-sided, 18-sector 
OF8H fixed disk 

OF9H 3.5", 2-sided, 9-sector 
OF9H 5.25", 2-sided, 15-sector 
OFCH 5.25", 1-sided, 9-sector 
OFDH 5.25", 2-sided, 9-sector 
OFEH 5.25", 1-sided, 8-sector 
OFFH 5.25", 2-sided, 8-sector 


Figure 14-8. Current valid MS-DOS codes for the media descriptor byte of the request 
header, assuming bit 13 in the attribute word of the driver header is zero. 
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MS-DOS responds to the results of the media-check function in the fol- 
lowing ways: 


= If the disk has not been changed, MS-DOS proceeds with the disk 
access. 


= Ifthe disk has been changed, MS-DOS invalidates all buffers associated 
with this unit, including buffers containing data waiting to be written 
(this data is simply lost), performs a BUILD BPB call, and then reads 
the disk’s FAT and directory. 


a If the disk-change status is unknown, the action taken by MS-DOS de- 
pends upon the state of its internal buffers. If data that needs to be 
written out is present in the buffers, MS-DOS assumes no disk change 
has occurred and writes the data (taking the risk that, if the disk really 
was changed, the file structure on the new disk may be damaged). If 
the buffers are empty or have all been previously flushed to the disk, 
MS-DOS assumes that the disk was changed, and then proceeds as 
described above for the disk-changed return code. 


If bit 11 of the device-header attribute word is set (that is, the driver sup- 
ports the optional open/close/removable-media functions), the host sys- 
tem is MS-DOS version 3.0 or later, and the function returns the disk- 
changed code (—1), the function must also return the segment and offset 
of the ASCIIZ volume label for the previous disk in the drive. (If the driver 
does not have the volume label, it can return a pointer to the ASCIIZ string 
NO NAME.) If MS-DOS determines that the disk was changed with un- 
written data still present in its buffers, it issues a critical-error OFH (invalid 
disk change). Application programs can trap this critical error and prompt 
the user to replace the original disk. 


The media-check function is called with 


RH + 1 BYTE Unit code 

RH + 2 BYTE Command code = 1 
RH + 13 BYTE Media descriptor byte 
It returns 


RH + 3 WORD Status 
RH + 14 BYTE Media-change code: 
—1 if disk changed 
0 if don’t know whether disk changed 
1 if disk not changed 
RH+15 =DWORD Pointer to previous volume label, if device attribute bit 
11 = 1 and disk has been changed (MS-DOS versions 3.0 
and later) 
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Function 02H (2): Build BIOS Parameter Block (BPB) 


The build BPB function applies only to block devices, and in character- 
device drivers should do nothing except set the done flag. The kernel uses 
this function to get a pointer to the valid BPB (see Figure 14-7) for the cur- 
rent disk and calls it when the disk-changed code is returned by the 
media-check routine or the don’t-know code is returned and there are no 
dirty buffers (buffers with changed data that have not yet been written to 
disk). Thus, a call to this function indicates that the disk has been legally 
changed. 


The build BPB function receives a pointer to a one-sector buffer in the re- 
quest header. If bit 13 in the driver header’s attribute word is zero, the 
buffer contains the first sector of the FAT (which includes the media iden- 
tification byte) and should not be altered by the driver. If bit 13 is set, the 
driver can use the buffer as scratch space. 


The build BPB function is called with 


RH + 1 BYTE Unit code 
RH + 2 BYTE Command code = 2 
RH + 13 BYTE Media descriptor byte 


RH + 14 DWORD Buffer address 


It returns 


RH + 3 WORD Status 
RH + 18 DWORD Pointer to new BPB 


Under MS-DOS versions 3.0 and later, if bit 11 of the header’s device at- 
tribute word is set, this routine should also read the volume label off the 
disk and save it. 


Function 03H (3): I/O-Control Read 
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The IOCTL read function allows the device driver to pass information di- 
rectly to the application program. This function is called only if bit 14 is 
set in the device attribute word. MS-DOS performs no error check on 
IOCTLI/O calls. 


The IOCTL read function is called with 


RH + 1 BYTE Unit code (block devices) 
RH + 2 BYTE Command code = 3 
RH + 13 BYTE Media descriptor byte 


RH + 14 DWORD _ Transfer address 
RH + 18 WORD Byte/sector count 
RH + 20 WORD Starting sector number (block devices) 
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It returns 


RH + 3 WORD Status 
RH + 18 WORD Actual bytes or sectors transferred 


Function 04H (4): Read 


The read function transfers data from the device into the specified 
memory buffer. If an error is encountered during the read, the function 
must set the error status and, in addition, report the number of bytes or 
sectors successfully transferred; it is not sufficient to simply report an 
error. 


The read function is called with 


RH +1 BYTE Unit code (block devices) 
RH + 2 BYTE Command code = 4 
RH + 13 BYTE Media descriptor byte 


RH + 14 DWORD _ Transfer address 
RH + 18 WORD Byte/sector count 
RH + 20 WORD Starting sector number (block devices) 


For block-device read operations in MS-DOS version 4, if the logical unit is 
larger than 32 MB and bit 1 of the driver’s attribute word is set, the follow- 
ing request structure is used instead: 


RH + 1 BYTE Unit code 
RH + 2 BYTE Command code = 4 
RH + 13 BYTE Media descriptor byte 


RH + 14 DWORD _ Transfer address 

RH + 18 WORD Sector count 

RH + 20 WORD Contains —1 to signal use of 32-bit sector number 
RH + 26 DWORD 32-bit starting sector number 


The read function returns 


RH + 3 WORD Status 

RH + 18 WORD Actual bytes or sectors transferred 

RH + 22 DWORD Pointer to volume label if error OFH is returned (MS-DOS 
versions 3.0 and later) 


Under MS-DOS versions 3.0 and later, this routine can use the count of 
open files maintained by the open and close functions (ODH and OEH) 
and the media descriptor byte to determine whether the disk has been il- 
legally changed. 
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Function 05H (5): Nondestructive Read 
The nondestructive read function applies only to character devices, and in 
block devices it should do nothing except set the done flag. It returns the 
next character that would be obtained with a read function (command 
code 4), without removing that character from the driver’s internal buffer. 
MS-DOS uses this function to check the console driver for pending Con- 
trol-C characters during other operations. 


The nondestructive read function is called with 


RH + 2 BYTE Command code = 5 


It returns 


RH + 3 WORD Status 
If busy bit = 0, at least one character is waiting 
If busy bit = 1, no characters are waiting 

RH + 13 BYTE Character (if busy bit = 0) 


Function 06H (6): Input Status 

The input-status function applies only to character devices, and in block- 
device drivers it should do nothing except set the done flag. This function 
returns the current input status for the device, allowing MS-DOS to test 
whether characters are waiting in a type-ahead buffer. If the character 
device does not have a type-ahead buffer, the input-status routine should 
always return the busy bit equal to zero, so that MS-DOS will not wait 
forever to call the read (04H) or nondestructive read (05H) function. 


The input-status function is called with 


RH + 2 BYTE Command code = 6 


It returns 


RH + 3 WORD Status: 
If busy bit = 1, read request goes to physical device. 
If busy bit = 0, characters already in device buffer and read 
request returns quickly. 


Function 07H (7): Flush Input Buffers 
The flush-input-buffers function applies only to character devices, and in 
block-device drivers it should do nothing except set the done flag. This 
function causes any data waiting in the input buffer to be discarded. 
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The flush-input-buffers function is called with 


RH +2 BYTE Command code = 7 


It returns 


RH + 3 WORD Status 


Function 08H (8): Write 


The write function transfers data from the specified memory buffer to the 
device. If an error is encountered during the write, the write function must 
set the error status and, in addition, report the number of bytes or sectors 
successfully transferred; it is not sufficient to simply report.an error. 


The write function is called with 


RH + 1 BYTE Unit code (block devices) 
RH + 2 BYTE Command code = 8 
RH + 13 BYTE Media descriptor byte 


RH + 14 DWORD _ Transfer address 
RH + 18 WORD Byte/sector count 
RH + 20 WORD Starting sector number (block devices) 


For block-device write operations in MS-DOS version 4, if the logical unit 
is larger than 32 MB and bit 1 of the driver's attribute word is set, the fol- 
lowing request structure is used instead: 


RH + 1 BYTE Unit code 
RH + 2 BYTE Command code = 8 
RH + 13 BYTE Media descriptor byte 


RH + 14 DWORD _ Transfer address 

RH + 18 WORD Sector count 

RH + 20 WORD Contains —1 to signal use of 32-bit sector number 
RH + 26 DWORD 32-bit starting sector number 


The write function returns 


RH + 3 WORD Status 

RH + 18 WORD Actual bytes or sectors transferred 

RH + 22 DWORD _ Pointer to volume label if error OFH returned (MS-DOS 
versions 3.0 and later) 


Under MS-DOS versions 3.0 and later, this routine can use the reference 
count of open files maintained by the open and close functions (ODH and 
OEH) and the media descriptor byte to determine whether the disk has 
been illegally changed. 
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Function 09H (9): Write with Verify 


The write-with-verify function transfers data from the specified memory 
buffer to the device. If feasible, it should perform a read-after-write 
verification of the data to confirm that the data was written correctly. 
Otherwise, Function 09H is exactly like Function 08H. 


Function 0AH (10): Output Status 


The output-status function applies only to character devices, and in 
block-device drivers it should do nothing except set the done flag. This 
function returns the current output status for the device. 


The output-status function is called with 


RH + 2 BYTE Command code = 10 (OAH) 


It returns 


RH + 3 WORD Status: 
If busy bit = 1, write request waits for completion of current 
request. 
If busy bit = 0, device idle and write request starts 
immediately. 


Function OBH (11): Flush Output Buffers 


The flush-output-buffers function applies only to character devices, and in 
block-device drivers it should do nothing except set the done flag. This 
function empties the output buffer, if any, and discards any pending out- 
put requests. 


The flush-output-buffers function is called with 
RH + 2 BYTE Command code = 11 (OBH) 


It returns 


RH + 3 WORD Status 


Function OCH (12): I/O-Control Write 
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The IOCTL write function allows an application program to pass control 
information directly to the driver. This function is called only if bit 14 is set 
in the device attribute word. MS-DOS performs no error check on IOCTL 
I/O calls. 
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The IOCTL write function is called with 


RH +1 BYTE Unit code (block devices) 
RH + 2 BYTE Command code = 12 (OCH) 
RH + 13 BYTE Media descriptor byte 


RH + 14 DWORD _ Transfer address 
RH + 18 WORD Byte/sector count 
RH + 20 WORD Starting sector number (block devices) 


It returns 


RH + 3 WORD Status 
RH + 18 WORD Actual bytes or sectors transferred 


Function 0DH (3): Device Open 


The device-open function is supported only under MS-DOS versions 3.0 
and later and is called only if bit 11 is set in the device attribute word of the 
device header. 


On block devices, the device-open function can be used to manage local 
buffering and to increment a reference count of the number of open files 
on the device. This capability must be used with care, however, because 
programs that access files through FCBs frequently fail to close them, thus 
invalidating the open-files count. One way to protect against this possibi- 
lity is to reset the open-files count to zero, without flushing the buffers, 
whenever the answer to a media-change call is yes and a subsequent build 
BPB call is made to the driver. 


On character devices, the device-open function can be used to send a 
device-initialization string (which can be set into the driver by an applica- 
tion program by means of an IOCTL write function) or to deny simulta- 
neous access to a character device by more than one process. Note that the 
predefined handles for the CON, AUX, and PRN devices are always open. 


The device-open function is called with 


RH +1 BYTE Unit code (block devices) 
RH + 2 BYTE Command code = 13 (ODH) 
It returns 


RH + 3 WORD Status 


Function OEH (14): Device Close 


The device-close function is supported only under MS-DOS versions 3.0 
and later and is called only if bit 11 is set in the device attribute word of the 
device header. 
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On block devices, this function can be used to manage local buffering and 
to decrement a reference count of the number of open files on the device; 
when the count reaches zero, all files have been closed and the driver 
should flush buffers because the user may change disks. 


On character devices, the device-close function can be used to send a 
device-dependent post-I/O string such as a formfeed. (This string can be 
set into the driver by an application program by means of an IOCTL write 
function.) Note that the predefined handles for the CON, PRN, and AUX 
devices are never closed. 


The device-close function is called with 

RH +1 BYTE Unit code (block devices) 
RH + 2 BYTE Command code = 14 (OEH) 
It returns 


RH + 3 WORD Status 


Function OFH (15): Removable Media 


The removable-media function is supported only under MS-DOS versions 
3.0 and later and only on block devices; in character-device drivers it 
should do nothing except set the done flag. This function is called only if 
bit 11 is set in the device attribute word in the device header. 


The removable-media function is called with 
RH +1 BYTE Unit code 

RH +2 BYTE Command code = 15 (OFH) 
It returns 


RH + 3 WORD Status: 
If busy bit = 1, medium nonremovable 
If busy bit = 0, medium removable 


Function 10H (16): Output Until Busy 
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The output-until-busy function is supported only under MS-DOS versions 
3.0 and later, and only on character devices; in block-device drivers it 
should do nothing except set the done flag. This function transfers data 
from the specified memory buffer to a device, continuing to transfer bytes 
until the device is busy. It is called only if bit 13 of the device attribute 
word is set in the device header. 
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This function is an optimization included specifically for the use of print 
spoolers. It is not an error for this function to return a number of bytes 
transferred that is less than the number of bytes requested. 


The output-until-busy function is called with 


RH + 2 BYTE Command code = 16 (10H) 
RH + 14 DWORD _ Transfer address 
RH + 18 WORD Byte count 


It returns 


RH + 3 WORD Status 
RH + 18 WORD Actual bytes transferred 


Function 13H (19) Generic IOCTL 


The generic IOCTL function is supported only under MS-DOS versions 3.2 
and later and is called only if bit 6 is set in the device attribute word of the 
device header. This function corresponds to the MS-DOS generic IOCTL 
service supplied to application programs by Int 21H Function 44H Sub- 
functions OCH and ODH. 


The generic IOCTL function is passed a category (major) code, a function 
(minor) code, the contents of the SI and DI registers at the point of the 
IOCTL call, and the segment and offset of a data buffer. This buffer in turn 
contains other information whose format depends on the major and 
minor IOCTL codes passed in the request header. The driver must inter- 
pret the major and minor codes in the request header and the contents of 
the additional buffer to determine which operation it will carry out, then 
set the done flag in the request-header status word, and return any other 
applicable information in the request header or the data buffer. 


Services that the generic IOCTL function may invoke, if the driver sup- 
ports them, include configuration of the driver for nonstandard disk for- 
mats, reading and writing entire disk tracks of data, and formatting and 
verifying tracks. The generic IOCTL function has been designed to be 
open-ended, so that it can be used to easily extend the device-driver 
definition under future versions of MS-DOS. 


The generic IOCTL function is called with 


RH +1 BYTE Unit number (block devices) 
RH + 2 BYTE Command code = 19 (13H) 
RH + 13 BYTE Category (major) code 

RH + 14 BYTE Function (minor) code 


RH +15 WORD SI register contents 
RH + 17 WORD DI register contents 
RH + 19 DWORD _ Address of generic IOCTL data packet 


Installable Device Drivers 279 


It returns 


RH + 3 WORD Status 


Function 17H (23): Get Logical Device 


The get-logical-device function is supported only under MS-DOS versions 
3.2 and later and only on block devices; in character-device drivers it 
should do nothing except set the done bit in the status word. This function 
is called only if bit 6 is set in the device attribute word of the device 
header. It corresponds to the get-logical-device-map service supplied to 
application programs through Int 21H Function 44H Subfunction OEH. 


The get-logical-device function returns a code for the last drive letter used 
to reference the device; if only one drive letter is assigned to the device, 
the returned unit code should be zero. Thus, this function can be used to 
determine whether more than one drive letter is assigned to the same 
physical device. 


The get-logical-device function is called with 


RH + 1 BYTE Unit code 
RH + 2 BYTE Command code = 23 (17H) 


It returns 


RH + 1 BYTE Last unit referenced, or zero 
RH + 3 WORD Status 


Function 18H (24): Set Logical Device 

The set-logical-device function is supported only under MS-DOS versions 
3.2 and later and only on block devices; in character-device drivers it 
should do nothing except set the done bit in the status word. This function 
is called only if bit 6 is set in the device attribute word of the device 
header. It corresponds to the set-logical-device-map service supplied to 
application programs by MS-DOS through Int 21H Function 44H Subfunc- 
tion OFH. 


The set-logical-device function informs the driver of the next logical- 
drive identifier that will be used to reference the physical device. The unit 
code passed by the MS-DOS kernel in this case is zero-based relative to 
the number of logical drives supported by this particular driver. For ex- 
ample, if the driver supports two floppy-disk units (A and B), only one 
physical floppy-disk drive exists in the system, and the set-logical-device 
function is called with a unit number of 1, the driver is being informed that 
the next read or write request from the kernel will be directed to drive B. 
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The set-logical-device function is called with 


RH +1 BYTE Unit code . 
RH + 2 BYTE Command code = 24 (18H) 
It returns 


RH + 3 WORD Status 


The Processing of a Typical I/O Request 


An application program requests an I/O operation from MS-DOS by load- 
ing registers with the appropriate values and executing an Int 21H. This 
results in the following sequence of actions: 


1. MS-DOS inspects its internal tables and determines which device 
driver should receive the I/O request. 


2. MS-DOS creates a request-header data packet in a reserved area of 
memory. (Disk I/O requests are transformed from file and record infor- 
mation into logical-sector requests by MS-DOS'’s interpretation of the 
disk directory and FAT.) 


3. MS-DOS calls the device driver’s strat entry point, passing the address 
of the request header in the ES:BX registers. 


4. The device driver saves the address of the request header in a local 
variable and performs a FAR RETURN. 


5. MS-DOS calls the device driver’s intr entry point. 


6. The interrupt routine saves all registers, retrieves the address of the 
request header that was saved by the strategy routine, extracts the 
function code, and branches to the appropriate command-code sub- 
routine to perform the function. 


7. If a data transfer on a block device was requested, the driver’s read or 
write subroutine translates the logical-sector number into a head, track, 
and physical-sector address for the requested unit and then performs 
the I/O operation. Because a multiple-sector transfer can be requested 
in a single request header, a single request by MS-DOS to the driver can 
result in multiple read or write commands to the disk controller. 


8. When the requested function is complete, the interrupt routine sets 
the status word and any other required information into the request 
header, restores all registers to their state at entry, and performs a FAR 
RETURN. 
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9. MS-DOS translates the driver’s return status into the appropriate return 
code and carry-flag status for the MS-DOS Int 21H function that was 
requested and returns control to the application program. 


Note that a single request by an application program can result in MS-DOS 
passing many request headers to the driver. For example, attempting to 
open a file in a subdirectory on a previously unaccessed disk drive might 
require the following actions: 


= Reading the disk’s boot sector to get the BPB 


# Reading from one to many sectors of the root directory to find the en- 
try for the subdirectory and obtain its starting-cluster number 


= Reading from one to many sectors of both the FAT and the subdirectory 
itself to find the entry for the desired file 


The CLOCK Driver: A Special Case 


MS-DOS uses the CLOCK device for marking file control blocks and direc- 
tory entries with the date and time, as well as for providing the date and 
time services to application programs. This device has a unique type of 
interaction with MS-DOS—a 6-byte sequence is read from or written to 
the driver that obtains or sets the current date and time. The sequence has 


the following format: 
0 1 2 3 4 5 
Days Days Minutes Hours Seconds/ | Seconds 
low byte | high byte 100 


The value passed for days is a 16-bit integer representing the number of 
days elapsed since January 1, 1980. 


The clock driver can have any logical-device name because MS-DOS uses 
the CLOCK bit in the device attribute word of the driver’s device header to 
identify the device, rather than its name. On IBM PC systems, the clock 
device has the logical-device name CLOCK$. 


Writing and Installing a Device Driver 


Now that we have discussed the structure and capabilities of installable 
device drivers for the MS-DOS environment, we can discuss the mechani- 
cal steps of assembling and linking them. 
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Assembly 


Device drivers for MS-DOS always have an origin of zero but are other- 
wise assembled, linked, and converted into an executable module as 
though they were .COM files. (Although MS-DOS is also capable of loading 
installable drivers in the .EXE file format, this introduces unnecessary 
complexity into writing and debugging drivers and offers no significant 
advantages. In addition, it is not possible to use .EXE-format drivers with 
some IBM versions of MS-DOS because the .EXE loader is located in 
COMMAND.COM, which is not present when the installable device 
drivers are being loaded.) The driver should not have a declared stack 
segment and must, in general, follow the other restrictions outlined in 
Chapter 3 for memory-image (.COM) programs. A driver can be loaded 
anywhere, so beware that you do not make any assumptions in your code 
about the driver’s location in physical memory. Figure 14-9 presents a 
skeleton example that you can follow as you read the next few pages. 


(continued) 


Figure 14-9. DRIVER.ASM: A functional skeleton from which you can implement 
your own working device driver. 
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Figure 14-9. continued 
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Figure 14-9. continued 
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Figure 14-9. continued 
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Figure 14-9. continued 
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Figure 14-9. continued 


The driver’s device header must be located at the beginning of the file 
(offset 0000H). Both words in the link field in the header should be set to 
~1. The attribute word must be set up correctly for the device type and 
other options. The offsets to the strategy and interrupt routines must be 
relative to the same segment base as the device header itself. If the driver 
is for a character device, the name field should be filled in properly with 
the device’s logical name. The logical name can be any legal 8-character 
filename, padded with spaces and without a colon. Beware of accidentally 
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duplicating the names of existing character devices, unless you are inten- 
tionally superseding a resident driver. 


MS-DOS calls the strategy and interrupt routines for the device by means 
of an intersegment call (CALL FAR) when the driver is first loaded and in- 
stalled and again whenever an application program issues an I/O request 
for the device. MS-DOS uses the ES:BX registers to pass the strat routine a 
double-word pointer to the request header; this address should be saved 
internally in the driver so that it is available for use during the subsequent 
call to the intr routine. 


The command-code routines for function codes 0 through 12 (OCH) must 
be present in every installable device driver, regardless of device type. 
Functions 13 (ODH) and above are optional for drivers used with MS-DOS 
versions 3.0 and later and can be handled in one of the following ways: 


= Don’t implement them, and leave the associated bits in the device 
header cleared. The resulting driver will work in either version 2 or 
version 3 but does not take full advantage of the augmented func- 
tionality of version 3. 


= Implement them, and test the MS-DOS version during the initialization 
sequence, setting bits 6 and 11 of the device header appropriately. 
Write all command-code routines so that they test this bit and adjust to 
accommodate the host version of MS-DOS. Such a driver requires more 
work and testing but will take full advantage of both the version 2 and 
the version 3 environments. 


= Implement them, and assume that all the version 3 facilities are avail- 
able. With this approach, the resulting driver may not work properly 
under version 2. 


Remember that device drivers must preserve the integrity of MS-DOS. The 
driver must preserve all registers, including flags (especially the direction 
flag and interrupt enable bits), and if the driver makes heavy use of the 
stack, it should switch to an internal stack of adequate depth (the MS-DOS 
stack has room for only 40 to 50 bytes when a driver is called), 


If you install a new CON driver, be sure to set the bits for standard input 
and standard output in the device attribute word in the device header. 


You'll recall that one file can contain multiple drivers. In this case, the 
device-header link field of each driver should point to the segment offset 
of the next, all using the same segment base, and the link field for the last 
driver in the file should be set to —1,-1. The initialization routines for all 
the drivers in the file should return the same break address. 
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Linking 
Use the standard MS-DOS linker to transform the .OBJ file that is output 
from the assembler into a relocatable EXE module. Then, use the 
EXE2BIN utility (see Chapter 4) to convert the .EXE file into a memory- 
image program. The extension on the final driver file can be anything, but 
BIN and .SYS are most commonly used in MS-DOS systems, and it is 
therefore wise to follow one of these conventions. 


Installation 


After the driver is assembled, linked, and converted to a .BIN or .SYS file, 
copy it to the root directory of a bootable disk. If it is a character-device 
driver, do not use the same name for the file as you used for the logical 
device listed in the driver’s header, or you will not be able to delete, copy, 
or rename the file after the driver is loaded. 


Use your favorite text editor to add the line 


DEVICE=(D:]|[PATHIFILENAME.EXT 


to the CONFIG.SYS file on the bootable disk. (In this line, D: is an op- 
tional drive designator and FILENAME.EXT is the name of the file con- 
taining your new device driver. You can include a path specification in the 
entry if you prefer not to put the driver file in your root directory.) Now re- 
start your computer system to load the modified CONFIG.SYS file. 


During the MS-DOS boot sequence, the SYSINIT module (which is part of 
IO.SYS) reads and processes the CONFIG.SYS file. It loads the driver into 
memory and inspects the device header. If the driver is a character-device 
driver, SYSINIT links it into the device chain ahead of the other character 
devices; if it is a block-device driver, SYSINIT places it behind all pre- 
viously linked block devices and the resident block devices (Figures 14-10, 
14-11, and 14-12). It accomplishes the linkage by updating the link field in 
the device header to point to the segment and offset of the next driver in 
the chain. The link field of the last driver in the chain contains —1,-1. 


Next, SYSINIT calls the strat routine with a request header that contains a 
command code of zero, and then it calls the intr routine. The driver exe- 
cutes its initialization routine and returns the break address, telling MS- 
DOS how much memory to reserve for this driver. Now MS-DOS can pro- 
ceed to the next entry in the CONFIG.SYS file. 


You cannot supersede a built-in block-device driver—you can only add 
supplemental block devices. However, you can override the default system 
driver for a character device (such as CON) with an installed driver by 
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giving it the same logical-device name in the device header. When pro- 
cessing a character I/O request, MS-DOS always scans the list of installed 
drivers before it scans the list of default devices and takes the first match. 


NUL 


CON 


AUX 


|! 


PRN 


|! 


CLOCK 


Any other resident block 
or character devices 


Figure 14-10. MS-DOS device-driver chain before any installable device drivers 
have been loaded. 


NUL 


Installable character- 
device drivers 


CON 


AUX 


|! 


PRN 


CLOCK 


Any other resident block 
or character devices 


| 


Installable block- 
device drivers 


Figure 14-11. MS-DOS device-driver chain after installable device drivers have been 
loaded. 
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See eee ee ee eee Ee a a ee ea 


Strategy Interrupt 
Address Attribute routine routine Type Units Name 


00E3:0111 8004 OFD5S OFEO C NUL 
0070:0148 8013 008E 0099 C CON 
0070:01DD 8000 008E OO9F Cc AUX 
0070:028E 8000 008E OOAE C PRN 
0070:0300 8008 008E 00C3 C CLOCK 
0070:03CC 0000 OO8E 00C9 B 02 

0070:01EF 8000 008E 009F C COM1 
0070:02A0 8000 008E OOAE C LPT1 
0070:06FO 8000 OO8E 00B4 C LPT2 
0070:0702 8000 OO8E OOBA C LPT3 
0070:0714 8000 008E 00A5 c COM2 
End of 

device chain 


Figure 14-12. Example listing of device chain under MS-DOS version 2.1, “plain 
vanilla” IBM PC with no fixed disks or user device drivers. (C=character device, 
B=block device) 


Debugging a Device Driver 


The most important thing to remember when testing new device drivers is 
to maintain adequate backups and a viable fallback position. Don’t modify 
the CONFIG.SYS file and install the new driver on your fixed disk before it 
is proven! Be prudent—create a bootable floppy disk and put the modi- 
fied CONFIG.SYS file and the new driver on that for debugging. When 
everything is working properly, copy the finished product to its perma- 
nent storage medium. 


The easiest way to test a new device driver is to write a simple assembly- 
language front-end routine that sets up a simulated request packet and 
then performs FAR CALLs to the strat and intr entry points, exactly as 
MS-DOS would. You can then link the driver and the front end together 
into a .COM or .EXE file that can be run under the control of CodeView or 
another debugger. This arrangement makes it easy to trace each of the 
command-code routines individually, to observe the results of the I/O, 
and to examine the status codes returned in the request header. 


Tracing the installed driver when it is linked into the MS-DOS system in 
the normal manner is more difficult. Breakpoints must be chosen 
carefully, to yield the maximum possible information per debugging run. 
Because current versions of MS-DOS maintain only one request header in- 
ternally, the request header that was being used by the driver you are trac- 
ing will be overwritten as soon as your debugger makes an output request 
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to display information. You will find it helpful to add a routine to your ini- 
tialization subroutine that displays the driver’s load address on the console 
when you boot MS-DOS; you can then use this address to inspect the 
device-driver header and set breakpoints within the body of the driver. 


Debugging a device driver can also be somewhat sticky when interrupt 
handling is involved, especially .if the device uses the same interrupt- 
request priority level (IRQ level) as other peripherals in the system. 
Cautious, conservative programming is needed to avoid unexpected and 
unreproducible interactions with other device drivers and interrupt han- 
dlers. If possible, prove out the basic logic of the driver using polled I/O, 
rather than interrupt-driven I/O, and introduce interrupt handling only 
when you know the rest of the driver's logic to be solid. 


Typical device-driver errors or problems that can cause system crashes or 
strange system behavior include the following: 


= Failure to set the linkage address of the last driver in a file to —1 


= Overflow of the MS-DOS stack by driver-initialization code, corrupting 
the memory image of MS-DOS (can lead to unpredictable behavior dur- 
ing boot; remedy is to use a local stack) 


= Incorrect break-address reporting by the initialization routine (can 
lead to a system crash if the next driver loaded overwrites vital parts of 
the driver) 


=" Improper BPBs supplied by the build BPB routine, or incorrect BPB | 
pointer array supplied by the initialization routine (can lead to many 
confusing problems, ranging from out-of-memory errors to system 
boot failure) 


= Incorrect reporting of the number of bytes or sectors successfully 
transferred at the time an I/O error occurs (can manifest itself as a sys- 
tem crash after you enter R to the Abort, Retry, Ignore? prompt) 


Although the interface between the DOS kernel and the device driver is 
fairly simple, it is also quite strict. The command-code routines must per- 
form exactly as they are defined, or the system will behave erratically. 
Even a very subtle discrepancy in the action of a command-code routine 
can have unexpectedly large global effects. 
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Filters 


A filter is, essentially, a program that operates on a stream of characters. 
The source and destination of the character stream can be files, another 
program, or almost any character device. The transformation applied by 
the filter to the character stream can range from an operation as simple as 
character substitution to one as elaborate as generating splines from sets 
of coordinates. 


The standard MS-DOS package includes three simple filters: SORT, which 
alphabetically sorts text on a line-by-line basis; FIND, which searches a 
text stream to match a specified string; and MORE, which displays text 
one screenful at a time. | 


System Support for Filters 


The operation of a filter program relies on two MS-DOS features that first 
appeared in version 2.0: standard devices and redirectable I/O. 


The standard devices are represented by five handles that are originally 
established by COMMAND.COM. Each process inherits these handles 
from its immediate parent. Thus, the standard device handles are already 
open when a process acquires control of the system, and it can use them 
with Interrupt 21H Functions 3FH and 40H for read and write operations 
without further preliminaries. The default assignments of the standard 
device handles are as follows: | 


ee 


Handle Name Default device 
0 stdin (standard input) CON 
1 stdout (standard output) CON 
2 stderr (standard error) CON 
3 stdaux (standard auxiliary) AUX 
4 stdprn (standard printer) PRN 


The CON device is assigned by default to the system’s keyboard and video 
display. AUX and PRN are respectively associated by default with COM1 
(the first physical serial port) and LPT] (the first parallel printer port). You 
can use the MODE command to redirect LPT1 to one of the serial ports; 
the MODE command will also redirect PRN. 


When executing a program by entering its name at the COMMAND.COM 
prompt, you can redirect the standard input, the standard output, or both 
from their default device (CON) to another file, a character device, or a 
process. You do this by including one of the special characters <, >, >>, 
and ; in the command line, in the form shown on the following page. 
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Symbol Effect 


< file Takes standard input from the specified file instead of the 
keyboard. 

< device Takes standard input from the named device instead of the 
keyboard. 

> file Sends standard output to the specified file instead of the display. 

>> file Appends standard output to the current contents of the specified 
file instead of sending it to the display. 

> device Sends standard output to the named device instead of the display. 

pl i p2 Routes standard output of program pi to become the standard 


input of program p2. (Output of p/ is said to be piped to p2.) 


For example, the command 
C>SORT <MYFILE.TXT >PRN <Enter> 


causes the SORT filter to read its input from the file MYFILE.TXT, sort the 
lines alphabetically, and write the resulting text to the character device 
PRN (the logical name for the system’s list device). 


The redirection requested by the <, >, >>, and | characters takes place at 
the level of COMMAND.COM and is invisible to the program it affects. 
Any other process can achieve a similar effect by redirecting the standard 
input and standard output with Int 21H Function 46H before calling the 
EXEC function (int 21H Function 4BH) to run a child process. 


Note that if a program circumvents MS-DOS to perform its input and out- 
put, either by calling ROM BIOS functions or by manipulating the key- 
board or video controller directly, redirection commands placed in the 
program’s command line do not have the expected effect. 


How Filters Work 


By convention, a filter program reads its text from the standard input 
device and writes the results of its operations to the standard output 
device. When it reaches the end of the input stream, the filter simply 
terminates. As a result, filters are both flexible and simple. 


Filter programs are flexible because they do not know, and do not care 
about, the source of the data they process or the destination of their out- 
put. Thus, any character device that has a logical name within the system 
(CON, AUX, COM1, COM2, PRN, LPT1, LPT2, LPT3, and so on), any file on 
any block device (local or network) known to the system, or any other 
program can supply a filter’s input or accept its output. If necessary, you 
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can concatenate several functionally simple filters with pipes to perform 
very complex operations. 


Although flexible, filters are also simple because they rely on their parent 
processes to supply standard input and standard output handles that have 
already been appropriately redirected. The parent must open or create 
any necessary files, check the validity of logical character-device names, 
and load and execute the preceding or following process in a pipe. The 
filter concerns itself only with the transformation it applies to the data. 


Building a Filter 
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Creating a new filter for MS-DOS is a straightforward process. In its 
simplest form, a filter need only use the handle-oriented read (Interrupt 
21H Function 3FH) and write (Interrupt 21H Function 40H) functions to 
get characters or lines from standard input and send them to standard out- 
put, performing any desired alterations on the text stream on a character- 
by-character or line-by-line basis. 


Figures 15-1 and 15-2 contain prototype character-oriented filters in both 
assembly language and C. In these examples, the translate routine, which 
is called for each character transferred from the standard input to the stan- 
dard output, does nothing at all. As a result, both filters function rather 
like a very slow COPY command. You can quickly turn these primitive fil- 
ters into useful programs by substituting your own translate routine. 


If you try out these programs, you'll notice that the C prototype filter runs 
much faster than its MASM equivalent. This is because the C runtime li- 
brary is performing hidden blocking and deblocking of the input and out- 
put stream, whereas the MASM filter is doing exactly what it appears to be 
doing: making two calls to MS-DOS for each character processed. You can 
easily restore the MASM filter’s expected speed advantage by adapting it 
to read and write lines instead of single characters. 
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(continued) 


Figure 15-1. PROTO.ASM, the source code for a prototype character-oriented 
MASM filter. 
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Figure 15-1. continued 


3 from 
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Figure 15-2. PROTO.C, the source code for a prototype character-oriented C filter. 


The CLEAN Filter 


As a more practical example of MS-DOS filters, let’s look at a simple but 
very useful filter called CLEAN. Figures 15-3 and 15-4 show the assembly- 
language and C source code for this filter. CLEAN processes a text stream 
by stripping the high bit from all characters, expanding tabs to spaces, and 
throwing away all control codes except carriage returns, linefeeds, and 
formfeeds. Consequently, CLEAN can transform almost any kind of word- 
processed document file into a plain ASCII text file. 


Filters 


“Eigen tab code 


“ASCII space code: 
cert z ke Ot file. 


aw width of tab stop 


oe size of ‘Anput and” 
3 output buffers es 


oe standard. cueput handle 
; standard error handle 


“save Ds: 0000 for ‘final 
return to MS-DOS, in case. 


oe 
, 
s 
» 


(continued) 


Figure 15-3. CLEAN.ASM, the source code for the MASM version of the CLEAN /ilter. 
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(continued) 
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Figure 15-3. continued 


_ clean: call ~ ; write: char to } stdout 
gnc clean2 ss: GF disk not full, 
. : jeget another ‘character 


a oe es failed. 
"mov dx, offset msg2 : DS: OX = error message 

“ogo MOV. ex, msg2_len. OX. = message length | 

mov. —sbx, stderr ss BX = » standard error handie 
mov ah, 40h -: function 40h = write 
ante 2h 2 i transfer to MS-DOS 


| ues ee terminate oe 
“3 -return code =] 


clean6: mov —ax,column=—s;:- tab code detected 
: 7 ies ; tabsiz - (column MOD tabsiz) 
$s nu f spaces, needed — 
‘to move to next tab stop a 


we 


clean7: Save spaces counter | 


al, blank | 
pute. 


clean8: call 


“function 4 4ch - terminate ae 
—¢ return code ie 
z Praneteh to ws<0 “DOS | 


clean endp a 


| at charseter From, stdin. 

3; returns carry = ] if 

send of. input, else - 
| So char, carry | = 0. “ 


(continued) 


306 = Programming for MS-DOS 


Figure 15-3. continued 
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(continued) 
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Figure 15-3. continued 
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(continued) 


Figure 15-4. CLEAN.C, the source code for the C version of the CLEAN filter. 
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(continued) 
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Figure 15-4. continued 


When using the CLEAN filter, you must specify the source and destination 
files with redirection parameters in the command line; otherwise, CLEAN 
will simply read the keyboard and write to the display. For example, to 
filter the document file MYFILE.DOC and leave the result in the file 
MYFILE.TXT, you would enter the following command: 


C>CLEAN <MYFILE.DOC >MYFILE.TXT <Enter> 


(Note that the original file, MYFILE.DOC, is unchanged.) 


One valuable application of this filter is to rescue assembly-language 
source files. If you accidentally edit such a source file in document mode, 
the resulting file may cause the assembler to generate spurious or confus- 
ing error messages. CLEAN lets you turn the source file back into some- 
thing the assembler can cope with, without losing the time you spent to 
edit it. 


Another handy application for CLEAN is to list a word-processed docu- 
ment in raw form on the printer, using a command such as 


C>CLEAN <MYFILE.DOC >PRN <Enter> 
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Contrasting the C and assembly-language versions of this filter provides 
some interesting statistics. The C version contains 79 lines and compiles to 
a 5889-byte .EXE file, whereas the assembly-language version contains 
265 lines and builds an 1107-byte .EXE file. The size and execution-speed 
advantages of implementing such tools in assembly language is obvious, 
even compared with such an excellent compiler as the Microsoft C 
Optimizing Compiler. However, you must balance performance consid- 
erations against the time and expense required for programming, par- 
ticularly when a program will not be used very often. 
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Compatibility and Po rtability 


At the beginning of this book, we surveyed the history of MS-DOS and 
Saw that new versions come along nearly every year, loosely coupled to 
the introduction of new models of personal computers. We then focused 
on each of the mainstream issues of MS-DOS applications programming: 
the user interface; mass storage; memory management; control of “child” 
processes; and special classes of programs, such as filters, interrupt han- 
dlers, and device drivers. 


It's now time to close the circle and consider two global concerns of MS- 
DOS programming: compatibility and portability. For your programs to 
remain useful in a constantly evolving software and hardware environ- 
ment, you must design them so that they perform reliably on any reason- 
able machine configuration and exploit available system resources; in 
addition, you should be able to upgrade them easily for new versions of 
MS-DOS, for new machines, and, for that matter, for completely new envi- 
ronments such as MS OS/2. 


Degrees of Compatibility 
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If we look at how existing MS-DOS applications use the operating system 
and hardware, we find that we can assign them to one of four categories: 


= MsS-DOS—compatible applications 

= ROM BIOS—compatible applications 
= Hardware-compatible applications 
# “Ill-behaved” applications 


MS-DOS—compatible applications use only the documented MS-DOS 
function calls and do not call the ROM BIOS or access the hardware di- 
rectly. They use ANSI escape sequences for screen control, and their input 
and output is redirectable. An MS-DOS—compatible application will run 
on any machine that supports MS-DOS, regardless of the machine config- 
uration. Because of the relatively poor performance of MS-DOS’s built-in 
display and serial port drivers, few popular programs other than com- 
pilers, assemblers, and linkers fall into this category. 


ROM BlOS—compatible applications use the documented MS-DOS and 
ROM BIOS function calls but do not access the hardware directly. As re- 
cently as three years ago, this strategy might have significantly limited a 
program’s potential market. Today, the availability of high-quality IBM- 
compatible ROM BlIOSes from companies such as Phoenix has ensured 
the dominance of the IBM ROM BIOS standard; virtually no machines are 
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being sold in which a program cannot rely as much on the ROM BIOS in- 
terface as it might on the MS-DOS interface. However, as we noted in 
Chapters 6 and 7, the ROM BIOS display and serial drivers are still not ade- 
quate to the needs of high-performance interactive applications, so the 
popular programs that fall into this category are few. 


Hardware-compatible applications generally use MS-DOS functions for 
mass storage, memory management, and the like, and use a mix of MS- 
DOS and ROM BIOS function calls and direct hardware access for their 
user interfaces. The amount of hardware dependence in such programs 
varies widely. For example, some programs only write characters and at- 
tributes into the video controller’s regen buffer and use the ROM BIOS to 
switch modes and position the cursor; others bypass the ROM BIOS video 
driver altogether and take complete control of the video adapter. As this 
book is written, the vast majority of the popular MS-DOS “productivity” 
applications (word processors, databases, telecommunications programs, 
and so on) can be placed somewhere in this category. 


“Tll-behaved” applications are those that rely on undocumented MS-DOS 
function calls or data structures, interception of MS-DOS or ROM BIOS in- 
terrupts, or direct access to mass storage devices (bypassing the MS-DOS 
file system). These programs tend to be extremely sensitive to their envi- 
ronment and typically must be “adjusted” in order to work with each new 
MS-DOS version or PC model. Virtually all popular terminate-and-stay- 
resident (TSR) utilities, network programs, and disk repair/optimization 
packages are in this category. 


Writing Well-Behaved MS-DOS Applications 


Your choice of MS-DOS functions, ROM BIOS functions, or direct hard- 
ware access to solve a particular problem must always be balanced against 
performance needs; and, of course, the user is the final judge of a pro- 
gram’s usefulness and reliability. Nevertheless, you can follow some basic 
guidelines, outlined below, to create well-behaved applications that are 
likely to run properly under future versions of MS-DOS and under multi- 
tasking program managers that run on top of MS-DOS, such as Microsoft 
Windows. 


Program structure 


Design your programs as .EXE files with separate code, data, and stack 
segments; shun the use of .COM files. Use the Microsoft conventions for 
segment names and attributes discussed in Chapter 3. Inspect the environ- 
ment block at runtime to locate your program’s overlays or data files; don’t 
“hard-wire” a directory location into the program. 
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Check host capabilities 


Obtain the MS-DOS version number with Int 21H Function 30H during 
your program’s initialization and be sure that all of the functions your 
program requires are actually available. If you find that the host MS-DOS 
version is inadequate, be careful about which functions you call to display 
an error message and to terminate. 


Use the enhanced capabilities of MS-DOS versions 3 and 4 when your 
program is running under those versions. For example, you can specify a 
sharing mode when opening a file with Int 21H Function 3DH, you can 
create temporary or unique files with Int 21H Functions 5AH and 5BH, and 
you can obtain extended error information (including a recommended 
recovery strategy) with Int 21H Function 59H. Section II of this book con- 
tains version-dependency information for each MS-DOS function. 


Input and output 


Use the handle file functions exclusively and extend full path support 
throughout your application (being sure to allow for the maximum pos- 
sible path length during user input of filenames). Use buffered I/O when- 
ever possible. The device drivers in MS-DOS versions 2.0 and later can 
handle strings as long as 64 KB, and performance will be improved if you 
write fewer, larger records as opposed to many short ones. 


Avoid the use of FCBs, the Int 25H or Int 26H functions, or the ROM BIOS 
disk driver. If you must use FCBs, close them when you are done with 
them and don’t move them around while they are open. Avoid reopening 
FCBs that are already open or reclosing FCBs that have already been 
closed—these seemingly harmless practices can cause problems when 
network software is running. 


Memory management 


During your program’s initialization, release any memory that is not 
needed by the program. (This is especially important for .COM pro- 
grams.) If your program requires extra memory for buffers or tables, allo- 
cate that memory dynamically when it is needed and release it as soon as 
it is no longer required. Use expanded memory, when it is available, to 
minimize your program’s demands on conventional memory. 


As a general rule, don’t touch any memory that is not owned by your pro- 
gram. To set or inspect interrupt vectors, use Int 21H Functions 25H and 
35H rather than editing the interrupt vector table directly. If you alter the 
contents of interrupt vectors, save their original values and restore them 


_ before the program exits. 
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Process management 


To isolate your program from dependencies on PSP structure and reloca- 
tion information, use the EXEC function (nt 21H Function 4BH) when 
loading overlays or other programs. Terminate your program with Int 21H 
Function 4CH, passing a zero return code if the program executes suc- 
cessfully and a nonzero code if an error is encountered. Your program's 
parent can then test this return code with Int 21H Function 4DH or, in a 
batch file, with the IF ERRORLEVEL statement. 


Exception handling 


Install Ctrl-C (int 23H) and critical-error (Int 24H) handlers so that your 
program cannot be terminated unexpectedly by the user’s entry of Ctrl-C 
or Ctrl-Break or by a hardware I/O failure. This is particularly important if 
your program uses expanded memory or installs its own interrupt 
handlers. 


ROM BIOS and Hardware-Compatible Applications 


When you feel the need to introduce ROM BIOS or hardware dependence 
for performance reasons, keep it isolated to small, well-documented pro- 
cedures that can be easily modified when the hardware changes. Use 
macros and equates to hide hardware characteristics and to avoid spread- 
ing “magic numbers” throughout your program. 


Check host capabilities 


If you use ROM BIOS functions in your program, you must check the ma- 
chine model at runtime to be sure that the functions your program needs 
are actually available. There is a machine ID byte at FO00:FFFEH whose 
value is interpreted as follows: 


F8H PS/2 Models 70 and 80 

FOH PC Convertible 

FAH PS/2 Model 30 

FBH PC/XT (later models) 

FCH PC/AT, PC/XT-286, PS/2 Models 50 and 60 
FDH PCjr 

FEH PC/XT (early models) 

FFH PC “Classic” 


In some cases, submodels can be identified; see Int 15H Function COH on 
page 573. Section III of this book contains version-dependency informa- 
tion for each ROM BIOS function. 


When writing your own direct video drivers, you must determine the type 
and capabilities of the video adapter by a combination of Int 10H calls, 
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reading ports, and inspection of the ROM BIOS data area at 0040:0000H 


_and the memory reserved for the EGA or VGA ROM BIOS, among other 


things. The techniques required are beyond the scope of this book but are 
well explained in Programmer's Guide to PC and PS/2 Video Systems 
(Microsoft Press, 1987). 


Avoid unstable hardware 


Some areas of IBM personal computer architecture have remained 
remarkably stable from the original IBM PC, based on a 4.77 MHz 8088, to 
today’s PS/2 Model 80, based on a 20 MHz 80386. IBM’s track record for 
upward compatibility in its video and serial communications controllers 
has been excellent; in many cases, the same hardware-dependent code 
that was written for the original IBM PC runs perfectly well on an IBM 
PS/2 Model 80. Other areas of relative hardware stability are: 


= Sound control via port 61H 
= The 8253 timer chip’s channels 0 and 2 (ports 40H, 42H, and 43H) 
= The game adapter at port 201H 


= Control of the interrupt system via the 8259 PIC’s mask register at 
port 21H 


However, direct sound generation and manipulation of the 8253 timer or 
8259 PIC are quite likely to cause problems if your program is run under a 
multitasking program manager such as Microsoft Windows or DesqView. 


Keyboard mapping, the keyboard controller, and the floppy and fixed disk 
controllers are areas of relative hardware instability. Programs that by- 
pass MS-DOS for keyboard or disk access are much less likely to function 
properly across the different PC models and are also prone to interfere 
with each other and with well-behaved applications. 


OS/2 Compatibility 


MS-DOS is upwardly compatible in several respects with OS/ 2, Microsoft’s 
multitasking protected-mode virtual memory operating system for 80286 
and 80386 computers. The OS/2 graphical user interface (the Presentation 
Manager) is nearly identical to Microsoft Windows 2.0. OS/2 versions 1.0 
and 1.1 use exactly the same disk formats as MS-DOS so that files may 
easily be moved between MS-DOS and OS/2 systems. Most important, 
OS/2 includes a module called the “DOS Compatibility Environment” or 
“3.x Box,” which can run one MS-DOS application at:a time alongside 
protected-mode OS/2 applications. 
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The 3.x Box traps Int 21H function calls and remaps them into OS/2 func- 
tion calls, emulating an MS-DOS 3.3 environment with the file-sharing 
module (SHARE.EXE) loaded but returning a major version number of 10 
instead of 3 for Int 21H Function 30H. The 3.x Box also supports most 
ROM BIOS calls, either by emulating their function or by interlocking the 
device and then calling the original ROM BIOS routine. In addition, the 
3.x Box maintains the ROM BIOS data area, provides timer ticks to appli- 
cations via Int 1CH, and supports certain undocumented MS-DOS services 
and data structures so that most TSR utilities can function properly. 
Nevertheless, the 3.x Box’s emulation of MS-DOS is not perfect, and you 
must be aware of certain constraints on MS-DOS applications running 
under OS/2. 


The most significant restriction on an MS-DOS application is that it does 
not receive any CPU cycles when it is in the background. That is, when a 
protected-mode application has been “selected,” so that the user can in- 
teract with it, the MS-DOS application is frozen. If the MS-DOS application 
has captured any interrupt vectors (such as the serial port or timer tick), 
these interrupts will not be serviced until the application is again selected 
and in the foreground. OS/2 must freeze MS-DOS applications when they 
are in the background because they execute in real mode and are thus not 
subject to hardware memory protection, nothing else ensures that they 
will not interfere with a protected-mode process that has control of the 
screen and keyboard. 


Use of FCBs is restricted in the 3.x Box, as it is under MS-DOS 3 or 4 with 
SHARE.EXE loaded. A file cannot be opened with an FCB if any other 
process is using it. The number of FCBs that can be simultaneously 
opened is limited to 16 or to the number specified in a CONFIG.SYS 
FCBS= directive. Even when the handle file functions are used, these 
functions may fail unexpectedly due to the activity of other processes (for 
example, if a protected-mode process has already opened the file with 
“deny all” sharing mode); most MS-DOS applications are not written with 
file sharing in mind, and they do not handle such errors gracefully. 


Direct writes to a fixed disk using Int 26H or Int 13H are not allowed. This 
prevents the file system from being corrupted, because protected-mode 
applications running concurrently with the MS-DOS application may also 
be writing to the same disk. Imagine the mess if a typical MS-DOS unerase 
utility were to alter the root directory and FAT at the same time that a 
protected-mode database program was updating its file and indexes! 
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MS-DOS applications that attempt to reprogram the 8259 to move the in- 
terrupt vector table or that modify interrupt vectors already belonging to 
an OS/2 device driver are terminated by the operating system. MS-DOS 
applications can change the 8259’s interrupt-mask register, disable and 
reenable interrupts at their discretion, and read or write any I/O port. The 
obvious corollary is that an MS-DOS program running in the 3.x Box can 
crash the entire OS/2 system at any time; this is the price for allowing real- 
mode applications to run at all. 
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The application program interface (API provided by OS/2 to protected- 
mode programs is quite different from the familiar Int 21H interface of MS- 
DOS and the OS/2 3.x Box. However, the OS/2 API is functionally a 
proper superset of MS-DOS. This makes it easy to convert well-behaved 
MS-DOS applications to run in OS/2 protected mode, whence they can be 
enhanced to take advantage of OS/2’s virtual memory, multitasking, and 
interprocess communication capabilities. 


To give you a feeling for both the nature of the OS/2 API and the practices 
that should be avoided in MS-DOS programming if portability to OS/2 is 
desired, I will outline my own Strategy for converting existing MS-DOS 
assembly-language programs to OS/2. For the purposes of discussion, I 
have divided the conversion process into five steps and have assigned 
each an easily remembered buzzword: 


1. Segmentation 

2. Rationalization 
3. Encapsulation 

4. Conversion 

5. Optimization 


The first three stages can (and should) be performed and tested in the MS- 
DOS environment; only the last two require OS/2 and the protected-mode 
programming tools. As you read on, you may notice that an MS-DOS pro- 
gram that follows the compatibility guidelines presented earlier in this 
chapter requires relatively little work to make it run in protected mode. 
This is the natural benefit of working with the operating system instead of 
against it. 
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Segmentation 


Most of the 80286’s protected-mode capabilities revolve around a change 
in the way memory is addressed. In real mode, the 80286 essentially emu- 
lates an 8088/86 processor, and the value in a segment register corre- 
sponds directly to a physical memory address. MS-DOS runs on the 80286 
in real mode. 


When an 80286 is running in protected mode, as it does under OS/2, an 
additional level of indirection is added to memory addressing.! A segment 
register holds a selector, which is an index to a table of descriptors. A de- 
scriptor defines the physical address and length of a memory segment, its 
characteristics (executable, read-only data, or read/write data) and access 
rights, and whether the segment is currently resident in RAM or has been 
swapped out to disk. Each time a program loads a segment register or ac- 
cesses memory, the 80286 hardware checks the associated descriptor and 
the program’s privilege level, generating a fault if the selector or memory 
operation is not valid. The fault acts like a hardware interrupt, allowing 
the operating system to regain control and take the appropriate action. 


This scheme of memory addressing in protected mode has two immediate 
consequences for application programs. The first is that application pro- 
grams can no longer perform arithmetic on the contents of segment regis- 
ters (because selectors are magic numbers and have no direct relationship 
to physical memory addresses) or use segment registers for storage of tem- 
porary values. A program must not load a segment register with anything 
but a legitimate selector provided by the OS/2 loader or resulting from an 
OS/2 memory allocation function call. The second consequence is that a 
program must strictly segregate machine code (“text”) from data, placing 
them in separate segments with distinct selectors (because a selector that 
is executable is not writable, and vice versa). 


Accordingly, the first step in converting a program for OS/2 is to turn it 
into a .EXE-type program that uses the Microsoft segment, class, and 
group conventions described in Chapter 3. At minimum, the program 
must have one code segment and one data segment, and should declare a 
group—with the special name DGROUP—that contains the “near” data 
segment, stack, and local heap Cif any). At the same time, you should 
remove or rewrite any code that performs direct manipulation of segment 
values. 


1 Although the 80386 has additional modes and addressing capabilities, current versions of 
OS/2 use the 80386 as though it were an 80286. 
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After restructuring and segmentation, reassemble and link your program 
and check to be sure it still works as expected under MS-DOS. Changing 
or adding segmentation often uncovers hidden addressing assumptions in 
the code, so it is best to track these problems down before making other 
substantive changes to the program. 


Rationalization 


Once you’ve successfully segmented your program so that it can be linked 
and executed as a .EXE file under MS-DOS, the next step is to rationalize 
your code. By rationalization I mean converting your program into a com- 
pletely well-behaved MS-DOS application. 


First, you must ruthlessly eliminate any elements that manipulate the 
peripheral device adapters directly, alter interrupt priorities, edit the sys- 
tem interrupt-vector table, or depend on CPU speed or characteristics 
(such as timing loops). In protected mode, control of the interrupt system 
is completely reserved to the operating system and its device drivers, I/O 
ports may be read or written by an application only under very specific 
conditions, and timing loops burn up CPU cycles that can be used by 
other processes. 


As I mentioned earlier in this chapter, display routines constitute the most 
common area of hardware dependence in an MS-DOS application. Direct 
manipulation of the video adapter and its regen buffer poses obvious 
difficulties in a multitasking, protected-memory environment such as 
OS/2. For porting purposes, you must convert all routines that write text to 
the display, modify character attributes, or affect cursor shape or position 
into Int 21H Function 40H calls using ANSI escape sequences or into ROM 
BIOS Int 10H calls. Similarly, you must convert all hardware-dependent 
keyboard operations to Int 21H Function 3FH or ROM BIOS Int 16H calls. 


Once all hardware dependence has been expunged from your program, 
your next priority is to make it well-behaved in its use of system memory. 
Under MS-DOS an application is typically handed all remaining memory 
in the system to do with as it will; under OS/2 the converse is true: A pro- 
cess is initially allocated only enough memory to hold its code, declared 
data storage, and stack. You can make the MS-DOS loader behave like 
the OS/2 loader by linking your application with the /CPARMAXALLOC 
switch. Alternatively, your program can give up all extra memory during 
its initialization with Int 21H Function 4AH, as recommended earlier in 
this chapter. 


After your program completes its initialization sequence, it should 
dynamically obtain and release any additional memory it may require for 
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buffers and tables with MS-DOS Int 21H Functions 48H and 49H. To en- 
sure compatibility with protected mode, limit the size of any single allo- 
cated block to 65,536 bytes or less, even though MS-DOS allows larger 
blocks to be allocated. 


Finally, you must turn your attention to file and device handling. Replace 
any calls to FCB file functions with their handle-based equivalents, 
because OS/2 does not support FCBs in protected mode at all. Check 
pathnames for validity within the application; although MS-DOS and the 
3.x Box silently truncate a name or extension, OS/2 refuses to open or 
create a file in protected mode if the name or extension is too long and 
returns an error instead. Replace any use of the predefined handles for the 
standard auxiliary and standard list devices with explicit opens of 
COM1, PRN, LPTI, and so on, using the resulting handle for read and write 
operations. OS/2 does not supply processes with standard handles for the 
serial communications port or printer. 


Encapsulation 


When you reach this point, with a well-behaved, segmented MS-DOS ap- 
plication in hand, the worst of a port to OS/2 is behind you. You are now 
ready to prepare your program for true conversion to protected-mode 
operation by encapsulating, in individual subroutines, every part of the 
program that is specific to the host operating system. The objective here is 
to localize the program’s “knowledge” of the environment into small pro- 
cedures that can be subsequently modified without affecting the re- 
mainder of the program. 


As an example of encapsulation, consider a typical call by an MS-DOS ap- 
plication to write a string to the standard output device (Figure 16-1). In 
order to facilitate conversion to OS/2, you would replace every instance of 
such a write to a file or device with a call to a small subroutine that “hides” 
the mechanics of the actual operating-system function call, as illustrated 
in Figure 16-2. 


Another candidate for encapsulation, which does not necessarily involve 
an operating-system function call, is the application’s code to gain access 
to command-line parameters, environment-block variables, and the name 
of the file it was loaded from. Under MS-DOS, this information is divided 
between the program segment prefix (PSP) and the environment block, as 
we saw in Chapters 3 and 12; under OS/2, there is no such thing as a PSP, 
and the program filename and command-line information are appended 
to the environment block. 
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stdout equ 


msg db 


;BX=handle 
‘We ckunekis 


Figure 16-1. Typical in-line code for an MS-DOS function call. This particular se- 
quence writes a string to the standard output device. Since the standard output might 
be redirected to a file without the program's knowledge, it must also check that all of 
the requested characters were actually written; if the returned length is less than the 


requested length, this usually indicates that the standard output has been redirected to 
a disk file and that the disk is full. 


(continued) 


Figure 16-2. Code from Figure 16-1 after “encapsulation.” The portion of the code 
that is operating-system dependent has been isolated inside a subroutine that is called 
from other points within the application. 
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Figure 16-2. continued 


‘error =—s—=~*é«S: mp Ferro 
ax,msg_len all characters written? 


; write to file or device 
Cal. with: 
poe = handle : 

CX =] enor oF data 


| if error, r, carry set 
sand AX =: error code. 


| gfunctiion 40h = write 
elie to Ms- DOS. me 


When you have completed the encapsulation of system services and ac- 
cess to the PSP and environment, subject your program once more to 
thorough testing under MS-DOS. This is your last chance, while you are 
still working in a familiar milieu and have access to your favorite debug- 
ging tools, to detect any subtle errors you may have introduced during the 
three conversion steps discussed thus far. 
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Conversion 


Next, you must rewrite each system-dependent procedure you created 
during the encapsulation stage to conform to the OS/2 protected-mode 
API. In contrast to MS-DOS functions, which are actuated through soft- 
ware interrupts and pass parameters in registers, OS/2 API functions are 
requested through a far call to a named entry point. Parameters are passed 
on the stack, along with the addresses of variables within the calling pro- 
gram’s data segment that will receive any results returned by the function. 
The status of an operation is returned in register AX—zero if the function 
succeeded, an error code otherwise. All other registers are preserved. 


Although it is not my intention here to provide a detailed introduction to 
OS/2 programming, Figure 16-3 illustrates the final form of our previous 
example, after conversion for OS/2. Note especially the addition of the 
extrn statement, the wien variable, and the simulation of the MS-DOS 
function status. This code may not be elegant, but it serves the purpose of 
limiting the necessary changes to a very small portion of the source file. 
Some OS/2 functions (such as DosOpen) require parameters that have no 
counterpart under MS-DOS; you can usually select reasonable values for 
these extra parameters that will make their existence temporarily invisible 
to the remainder of the application. 


(continued) 


Figure 16-3. Code from Figure 16-2 after “conversion.” The MS-DOS function call 
has been replaced with the equivalent OS/2 function call. Since the knowledge of the 
operating system has been hidden inside the subroutine by the previous encapsulation 
step, the surrounding program's requests for write operations should run unchanged. 
Note that the OS/2 function had to be declared as an external name with the “far” at- 
tribute, and that a variable named wien was added to the data segment of the 
application to receive the actual number of bytes written. 
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pioure 16-3. continued 


uae) 


ak aR: 
- writel — 
vy aK, wien” 


diskfull ce 


Pdxis seg msg 
mov ds,dx_ 


ce MOV. 


0 Pax a handle? 


he ee 

Ok os 
ca 

he dS 


owritel: ste 0. ee 


write 


dx, offset DGROUP:msg_ 
cx,msg_len 
: bx, stdout — 


pall characters written? 


we 


well ee we we 


: handle oe 
; address of. Fae oe 


eax oe 
_ pe | 


oe 


- if error, carry set. 
, an Ae tears pben ecsuciatttx : 


X= message length 


BX = handle 2 i. 
, + perform the write. 


jump if error 


write. to file or. device 
call with: 


cx = Tength of data 
ee 


and AX = bytes: written 


swlen . 


transfer to 0s/2. 
did write succeed? 
_ jump, write failed 


and Mas = Byres written a ae 


at error, return cy set 


; and AX = error. number 
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Figures 16-4, 16-5, and 16-6 list the OS/2 services that are equivalent to 
selected MS-DOS and ROM BIOS Int 21H, Int 10H, and Int 16H calls. MS- 
DOS functions related to FCBs and PSPs are not included in these tables 
because OS/2 does not support either of these structures. The MS-DOS 
terminate-and-stay-resident functions are also omitted. Because OS/2 is a 
true multitasking system, a process doesn’t need to terminate in order to 
stay resident while another process is running. 


MS-DOS Description OS/2 function 

Int 21H 

Function 

0 Terminate process DosExit 

1 Character input with echo KbdCharIn 

2 Character output VioWrtT TY 

3 Auxiliary input DosRead 

4 Auxiliary output DosWrite 

5 Printer output DosWrite 

6 Direct console I/O KbdCharIn, 
VioWrtT TY 

7 Unfiltered input without echo KbdCharIn 

8 Character input without echo KbdCharIn 

9 Display string VioWrtT TY 

OAH (10) Buffered keyboard input KbdStringIn 

OBH (11) Check input status KbdPeek 

OCH (12) Reset buffer and input KbdFlushBuffer, 
KbdCharIn 

ODH (13) Disk reset DosBufReset 

OEH (14) Select disk DosSelectDisk 

19H (25) Get current disk DosQCurDisk 

1BH (27) Get default drive data DosQFSInfo 

1CH (28) Get drive data DosQFSInfo 

2AH (42) Get date DosGetDateTime 

2BH (43) Set date DosSetDateTime 

2CH (44) Get time DosGetDateTime 

2DH (45) Set time DosSetDateTime 

2EH (46) Set verify flag DosSetVerify 

30H (48) Get MS-DOS version DosGetVersion 

36H (54) Get drive allocation DosQFSInfo 

information 


( continued) 


Figure 16-4. Table of selected MS-DOS function calls and their OS/2 counterparts. 
Note that OS/2 functions are typically more powerful and flexible than the corre- 
sponding MS-DOS functions, and that this is not a complete list of OS/2 services. 
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Figure 16-4. continued 


MS-DOS 
38H (56) 


39H (57) 
3AH (58) 
3BH (59) 
3CH (60) 
3DH (61) 
3EH (62) 
3FH (63) 
40H (64) 
41H (65) 
42H (66) 
43H (67) 


44H (68) 
45H (69) 
46H (70) 
47H (71) 
48H (72) 
49H (73) 
4AH (74) 
4BH (75) 
4CH (76) 


4DH (77) 
4EH (78) 
4FH (79) 
54H (84) 
56H (86) 
57H (87) 


59H (89) 
5BH (91) 
5CH (92) 
65H (101) 
66H (102) 
67H (103) 


68H (104) 
6CH (108) 


Description 


Get or set country 
information 

Create directory 

Delete directory 

Set current directory 

Create file 

Open file 

Close file 

Read file or device 

Write file or device 

Delete file 

Set file pointer 

Get or set file attributes 


I/O control OCTL) 

Duplicate handle 

Redirect handle 

Get current directory 

Allocate memory block 

Release memory block 

Resize memory block 

Execute program 

Terminate process with 
return code 

Get return code 

Find first file 

Find next file 

Get verify flag 

Rename file 

Get or set file date and time 


Get extended error 
information 

Create new file 

Lock or unlock file region 

Get extended country 
information 

Get or set code page 


Set handle count 
Commit file 
Extended open file 


OS/2 function 
DosGetCtryInfo 


DosMkdir 
DosRmdir 
DosChdir 
DosOpen 
DosOpen 
DosClose 
DosRead 
DosWrite 
DosDelete 
DosChgFilePtr 
DosQFileMode, 
DosSetFileMode 
DosDevIOCtl 
DosDupHandle 
DosDupHandle 
DosQCurDir 
DosAllocSeg 
DosFreeSeg 
DosReAllocSeg 
DosExecPgm 
DosExit 


DosCWait 
DosFindFirst 
DosFindNext 
DosQVerify 
DosMove 
DosQFileInfo, 
DosSetFileInfo 
DosErrClass 


DosOpen 
DosFileLocks — 
DosGetCtryInfo 


DosGetCp, 
DosSetCp 
DosSetMaxFH 
DosBufReset 
DosOpen 
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ROM BIOS Description OS/2 function 
Int 10H 

Function 

0 Select display mode VioSetMode 

1 Set cursor type VioSetCurType 
2 set cursor position VioSetCurPos 
3 Get cursor position VioGetCurPos 
6 Initialize or scroll window up VioScrollUp 

7 Initialize or scroll window down VioScrollDn 

8 Read character and attribute VioReadCellStr 
9 Write character and attribute VioWrtNCell 
OAH (10) Write character VioWrtNChar 
OEH (14) Write character in teletype mode VioWrt TTY 
OFH (15) Get display mode VioGetMode 
10H (16) Set palette, border color, etc. VioSetState 
13H (19) Write string in teletype mode VioWrtT TY 


Figure 16-5. Table of ROM BIOS Int 10H video-display driver functions used by MS- 
DOS applications and their OS/2 equivalents. This is not a complete list of OS/2 video 


Services. 

ROM BIOS Description OS/2 function 
Int 16H | 

Function 

0 Read keyboard character KbdCharIn 

1 Get keyboard status KbdPeek 

2 Get keyboard flags KbdGetStatus 


Figure 16-6. Table of ROM BIOS Int 16H keyboard driver functions used by MS-DOS 
applications and their OS/2 equivalents. This is not a complete list of OS/2 keyboard 


services. 


Optimization 
Once your program is running in protected mode, it is time to unravel 


some of the changes made for purposes of conversion and to introduce 
various optimizations. Three obvious categories should be considered: 


—_ 


. Modifying the program’s user-interface code for the more powerful 
OS/2 keyboard and display API functions. 


NO 


. Incorporating 80286-specific machine instructions where appropriate. 


Oe 


. Revamping the application to exploit the OS/2 facilities that are unique 
to protected mode. (Of course, the application benefits from OS/2’s 
virtual memory capabilities automatically; it can allocate memory until 
physical memory and disk swapping space are exhausted.) 
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Modifying subroutines that encapsulate user input and output to take ad- 
vantage of the additional functionality available under OS/2 is straight- 
forward, and the resulting performance improvements can be quite dra- 
matic. For example, the OS/2 video driver offers a variety of services that 
are far superior to the screen support in MS-DOS and the ROM BIOS, in- 
cluding high-speed display of strings and attributes at any screen position, 
“reading back” selected areas of the display into a buffer, and scrolling in 
all four directions. 


The 80286-specific machine instructions can be very helpful in reducing 
code size and increasing execution speed. The most useful instructions 
are the shifts and rotates by an immediate count other than one, the three- 
operand multiply where one of the operands is an immediate (literal) 
value, and the push immediate value instruction (particularly handy for 
setting up OS/2 function calls). For example, in Figure 16-3, the sequence 


mov ax, offset DGROUP:wien 
push ax 


could be replaced by the single instruction 
push offset DGROUP:wien 


Restructuring an application to take full advantage of OS/2’s protected- 
mode capabilities requires close study of both the application and the 
OS/2 API, but such study can pay off with sizable benefits in performance, 
ease of maintenance, and code sharing. Often, for instance, different parts 
of an application are concerned with I/O devices of vastly different 
speeds, such as the keyboard, disk, and video display. It both simplifies 
and enhances the application to separate these elements into 
subprocesses (called threads in OS/2) that execute asynchronously, com- 
municate through shared data structures, and synchronize with each 
other, when necessary, using semaphores. 


As another example, when several applications are closely related and 
contain many identical or highly similar procedures, OS/2 allows you to 
centralize those procedures in a dynamic link library. Routines in a 
dynamic link library are bound to a program at its load time (rather than 
by LINK, as in the case of traditional runtime libraries) and are shared by 
all the processes that need them. This reduces the size of each application 
EXE file and allows more efficient use of memory. Best of all, dynamic 
link libraries drastically simplify code maintenance; the routines in the li- 
braries can be debugged or improved at any time, and the applications 
that use them will automatically benefit the next time they are executed. 
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This section documents the services that the MS-DOS kernel provides to 
application programs via software interrupts 2OH-2FH. Each MS-DOS 
function is described in the same format: 


= A heading containing the function’s name, software interrupt and 
function number, and an icon indicating the MS-DOS version in which 
the function was first supported. You can assume that the function is 
available in all subsequent MS-DOS versions unless explicitly noted 
otherwise. 


= A synopsis of the actions performed by the function and the circum- 
stances under which it would be used. 


# Asummary of the function’s arguments. 


a The results and/or error indicators returned by the function. A com- 
prehensive list of error codes can be found in the entry for Int 21H 
Function 59H. 


a Notes describing special uses or dependencies of the function. 
= A skeleton example of the function’s use, written in assembly language. 


Version icons used in the synopsis, arguments, results, or Notes sections 
refer to specific minor or major versions, unless they include a + sign to in- 
dicate a version and all subsequent versions. 


For purposes of clarity, the examples may include instructions that would 
not be necessary if the code were inserted into a working program. For 
example, most of the examples explicitly set the segment registers when 
passing the address of a filename or buffer to MS-DOS; in real applica- 
tions, the segment registers are usually initialized once at entry to the pro- 
gram and left alone thereafter. 
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Int 21H Function Summary by Number 


Hex 


00H 
01H 
02H 
03H 
04H 
05H 
06H 
07H 
08H 
09H 
OAH 
0OBH 
0CH 
0DH 
OEH 
OFH 
10H 
11H 
12H 
13H 
14H 
15H 
16H 
17H 
18H 
19H 
1AH 
1BH 
1CH 
1DH 
1EH 
1FH 
20H 
21H 
22H 
23H 
24H 
25H 
26H 
27H 
28H 
29H 


1 Specifies whether file functions are FCB- or handle-related. 


Dec 


CONIA WW BR WN & © 


\9 


Function name 


Terminate Process 


Character Input with Echo 


Character Output 
Auxiliary Input 
Auxiliary Output 
Printer Output 
Direct Console I/O 


Vers F/H! 


1.0+ 
1.0+ 
1.0+ 
1.0+ 
1.0+ 
1.0+ 
1.0+ 


Unfiltered Character Input Without Echo 1.0+ 


Character Input Without Echo 


Display String 


Buffered Keyboard Input 


Check Input Status 


Flush Input Buffer and Then Input 


Disk Reset 
Select Disk 
Open File 

Close File 

Find First File 
Find Next File 
Delete File 
Sequential Read 
Sequential Write 
Create File 
Rename File 
Reserved 

Get Current Disk 
Set DTA Address 
Get Default Drive Data 
Get Drive Data 
Reserved 
Reserved 
Reserved 
Reserved 
Random Read 
Random Write 
Get File Size 


Set Relative Record Number 


Set Interrupt Vector 
Create New PSP 
Random Block Read 
Random Block Write 
Parse Filename 


1.0+ 
1.0+ 
1.0+ 
1.0+ 
1.0+ 
1.0+ 
1.0+ 
1.0+ 
1.0+ 
1.0+ 
1.0+ 
1.0+ 
1.0+ 
1.0+ 
1.0+ 
1.0+ 


Aaa may WH 


1.0+ 
1.0+ 
1.0+ 
2.0+ 


1.0+ 
1.0+ 
1.0+ 
1.0+ 
1.0+ 
1.0+ 
1.0+ F 
1.0+ F 
1.0+ 


rr] ‘rj ‘ri oT 
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Int 21H Function Summary by Number continued 


Hex Dec 
2AH 42 
2BH 43 
2CH 44 
2DH 45 
2EH 46 
2FH 47 
30H 48 
31H 49 
32H 50 
33H 51 
34H 52 
35H 53 
36H 54 
37H 55 
38H 56 
39H 57 
3AH 58 
3BH 59 
3CH 60 
3DH 61 
3EH 62 
3FH 63 
40H 64 
41H 65 
42H 66 
43H 67 
44H 68 
45H 69 
46H 70 
47H 71 
48H 72 
49H 73 
4AH 74 
4BH 75 
4CH 76 
4DH 7/7 
4EH 78 
4FH 79 
50H 80 
51H 81 
52H 82 
53H 83 
Section IT 


Function name 


Get Date 

Set Date 

Get Time 

Set Time 

Set Verify Flag 

Get DTA Address 

Get MS-DOS Version Number 
Terminate and Stay Resident 
Reserved | 
Get or Set Break Flag, Get Boot Drive 
Reserved 

Get Interrupt Vector 

Get Drive Allocation Information 
Reserved 

Get or Set Country Information 
Create Directory 

Delete Directory 

Set Current Directory 

Create File 

Open File 

Close File 

Read File or Device 

Write File or Device 

Delete File 

Set File Pointer 

Get or Set File Attributes 
IOCTL (I/O Control) 
Duplicate Handle 

Redirect Handle 

Get Current Directory 

Allocate Memory Block 
Release Memory Block 

Resize Memory Block 

Execute Program (EXEC) 
Terminate Process with Return Code 
Get Return Code 

Find First File 

Find Next File 

Reserved 

Reserved 

Reserved 

Reserved 


Vers 


1.0+ 
1.0+ 
1.0+ 
1.0+ 
1.0+ 
2.0+ 
2.0+ 
2.0+ 


2.0+ 


2.0+ 
2.0+ 


2.0+ 
2.0+ 
2.0+ 
2.0+ 
2.0+ 
2.0+ 
2.0+ 
2.0+ 
2.0+ 
2.0+ 
2.0+ 
2.0+ 
2.0+ 
2.0+ 
2.0+ 
2.0+ 
2.0+ 
2.0+ 
2.0+ 
2.0+ 
2.0+ 
2.0+ 
2.0+ 
2.0+ 


F/H 


Litictttotat 


oo 
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Int 21H Function Summary by Number continued 
Function name 


Hex 


54H 
55H 
56H 
57H 


Dec 


84 
85 
86 
87 
88 
89 
90 
91 
92 
93 
94 
95 


Get Verify Flag 

Reserved 

Rename File 

Get or Set File Date and Time 
Get or Set Allocation Strategy 
Get Extended Error Information 
Create Temporary File 

Create New File 

Lock or Unlock File Region 
Reserved 


2.0+ 
2.0+ H 
3.0+ 
3.0+ 
3.0+ 
3.0+ 
3.0+ 


oo 


Get Machine Name, Get or Set Printer Setup 3.1+ 


Device Redirection 
Reserved 

Reserved 

Get PSP Address 

Get DBCS Lead Byte Table 
Reserved 

Get Extended Country Information 
Get or Set Code Page 

Set Handle Count 
Commit File 

Reserved 

Reserved 

Reserved 

Extended Open File 


3.1+ 


: 


3.0+ 
2.25 only 


3.3+ 
3.3+ 
3.3+ 
3.3+ H 


4.0+ H 


Int 21H Function Summary by Category 


Hex 


01H 
02H 
03H 
04H 
05H 
06H 
07H 
08H 


Dec 
Character I/O 


1 


On AW &R W LN 


Function name 


Character Input with Echo 
Character Output 
Auxiliary Input 

Auxiliary Output 

Printer Output 

Direct Console I/O 


Vers F/H 


1.0+ 
1.0+ 
1.0+ 
1.0+ 
1.0+ 
1.0+ 


Unfiltered Character Input Without Echo 1.0+ 


Character Input Without Echo 


1.0+ 
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Int 21H Function Summary by Category continued 
i mm eee 


Hex Dec Function name Vers F/H 

09H 9 Display String 1.0+ 

OAH 10 Buffered Keyboard Input 1.0+ 

OBH 11 Check Input Status 1.0+ 

OCH 12 Flush Input Buffer and Then Input 1.0+ 

File Operations 

OFH 15 Open File 1.0+ F 

10H 16 Close File 1.0+ F 

11H 17 Find First File 1.0+ F 

12H 18 Find Next File 1.0+ F 

13H 19 Delete File 1.0+ F 

16H 22 Create File 1.0+ F 

17H 23 Rename File 1.0+ F 

23H 35 Get File Size 1.0+ F 

29H 4] Parse Filename 1.0+ F 

3CH 60 Create File 2.0+ H 

3DH 61 Open File 2.0+ H 

3EH 62 Close File 2.0+ H 

41H 65 Delete File 2.0+ H 

43H 67 Get or Set File Attributes 2.0+ 

45H 69 Duplicate Handle 2.0+ 

46H 70 Redirect Handle 2.0+ 

4EH 78 Find First File 2.0+ H 

4FH 79 Find Next File 2.0+ H 

56H 86 Rename File 2.0+ 

57H 87 Get or Set File Date and Time 2.0+ H 

5AH 90 Create Temporary File 3.0+ H 

5BH 91 Create New File 3.0+ H 

67H 103 Set Handle Count 3.3+ 

68H 104 Commit File 3.3+ H 

6CH 108 Extended Open File 4.0+ H 

Record Operations 

14H 20 Sequential Read 1.0+ F 

15H 21 Sequential Write 1.0+ F 

1AH 26 Set DTA Address 1.0+ 

21H 33 Random Read 1.0+ F 

22H 34 Random Write 1.0+ F 

24H 36 Set Relative Record Number 1.0+ F 

27H 39 Random Block Read 1.0+ F 

28H 40 Random Block Write 1.0+ F 

2FH 47 Get DTA Address 2.0+ 

3FH 63 Read File or Device 2.0+ H 

a ees 
(continued) 
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Int 21H Function Summary by Category continued 
Hex Dec Function name 


40H 64 Write File or Device 

42H 66 Set File Pointer 

5CH 92 Lock or Unlock File Region 
Directory Operations 

39H 57 Create Directory 

3AH 58 Delete Directory 

3BH 59 Set Current Directory 

47H 71 Get Current Directory 

Disk Management 

0ODH 13 Disk Reset 

OEH 14 Select Disk 

19H 25 Get Current Disk 

1BH 27 Get Default Drive Data 

1CH 28 Get Drive Data 

2EH 46 Set Verify Flag 

36H 54 Get Drive Allocation Information 
54H 84 Get Verify Flag 

Process Management 

00H 0 Terminate Process 

26H 38 Create New PSP 

31H 49 Terminate and Stay Resident 
4BH 75 Execute Program (EXEC) 
4CH 76 Terminate Process with Return Code 
4DH 77 Get Return Code 

62H 98 Get PSP Address 

Memory Management 

48H fz Allocate Memory Block 

49H 73 Release Memory Block 

4AH 74 Resize Memory Block 

58H 88 Get or Set Allocation Strategy 
Network Functions 

5EH 94 Get Machine Name, Get or Set Printer Setup 
5FH 95 Device Redirection 

Time and Date 

2AH 42 Get Date 

2BH 43 Set Date 

2CH 44 Get Time 

2DH 45 Set Time 


i 
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Int 21H Function Summary by Category continued 


Hex Dec Function name Vers F/H 
Miscellaneous System Functions 

25H 37 Set Interrupt Vector 1.0+ 
30H 48 Get MS-DOS Version Number 2.0+ 
33H 51 Get or Set Break Flag, Get Boot Drive 2.0+ 
35H 53 Get Interrupt Vector 2.0+ 
38H 56 Get or Set Country Information 2.0+ 
44H 68 IOCTL (I/O Control) 2.0+ 
59H 89 Get Extended Error Information 3.0+ 
63H 99 Get Lead Byte Table 2.25 only 
65H 101 Get Extended Country Information 33+ 
66H 102 Get or Set Code Page 3.3+ 
Reserved Functions 

18H 24 Reserved 

1DH 29 Reserved 

1EH 30 Reserved 

1FH 31 Reserved 

20H 32 Reserved 

32H 50 Reserved 

34H 52 Reserved 

37H 55 Reserved 

50H 80 Reserved 

51H 81 Reserved 

52H 82 Reserved 

53H 83 Reserved 

55H 85 Reserved 

5DH 93 Reserved 

60H 96 Reserved 

61H 97 Reserved 


64H 100 Reserved 
69H 105 Reserved 
6AH 106 Reserved 


6BH 107 Reserved 
ee a rae Ee ae eT 
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Int 20H [1.0] 
Terminate process 


Terminates the current process. This is one of several methods that a program can use to perform a final 
exit. MS-DOS then takes the following actions: 


= All memory belonging to the process is released. 


= File buffers are flushed and any open handles for files or devices owned by the 
process are closed. 


™ The termination handler vector (Int 22H) is restored from PSP:000AH. 

= The Ctrl-C handler vector (Int 23H) is restored from PSP:O00EH. 

a (2.0+] The critical-error handler vector (Int 24H) is restored from PSP:0012H. 
= Control is transferred to the termination handler. 


If the program is returning to COMMAND.COM, control transfers to the resident portion, and the tran- 
sient portion is reloaded if necessary. If a batch file is in progress, the next line of the file is fetched and 
interpreted; otherwise, a prompt is issued for the next user command. 


OO 


Call with: Cs = segment address of program segment prefix 


a OO 


Returns: Nothing 


OO 


Notes: ™ Any files that have been written to using FCBs should be closed before performing 

this exit call; otherwise, data may be lost. 

= Other methods of performing a final exit are: 
— Int 21H Function 00H 
— Int 21H Function 31H 
— Int 21H Function 4CH 
— Int 27H 

= (2.0+] Int 21H Functions 31H and 4CH are the preferred methods for termination, 
since they allow a return code to be passed to the parent process. 


= (3.0+] If the program is running on a network, it should remove all locks it has 
placed on file regions before terminating. 


a 


Example: — Terminate the current program, returning control to the program's parent. 


int 20h : transfer to MS-DOS 
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es 
Int 21H | [1.0] 


Function 00H 


Terminate process 
Reena eee a cee 


Terminates the current process. This is one of several methods that a program can use to perform a final 
exit. MS-DOS then takes the following actions: 


= All memory belonging to the process is released. 

= File buffers are flushed and any open handles for files or devices owned by the 
process are closed. 

The termination handler vector (Int 22H) is restored from PSP:O00AH. 

The Ctrl-C handler vector (Int 23H) is restored from PSP:000EH. 

[2.0+] The critical-error handler vector (Int 24H) is restored from PSP:0012H. 
Control is transferred to the termination handler. 


If the program is returning to COMMAND.COM, control transfers to the resident portion, and the tran- 
sient portion is reloaded if necessary. If a batch file is in progress, the next line of the file is fetched and 
interpreted; otherwise, a prompt is issued for the next user command. 


ee 
Call with: AH = 00H 


CS = segment address of program segment prefix 


eee 
Returns: Nothing 


SH ——— eee 


Notes: ™ Any files that have been written to using FCBs should be closed before performing 
this exit call; otherwise, data may be lost. 


= Other methods of performing a final exit are: 
— Int 20H 
— Int 21H Function 31H 
— Int 21H Function 4CH 
— Int 27H 

= [2.0+] Int 21H Functions 31H and 4CH are the preferred methods for termination, 
since they allow a return code to be passed to the parent process. 

= [3.0+] If the program is running on a network, it should remove all locks it has 
placed on file regions before terminating. 


eee 


Example: Terminate the current program, returning control to the program’s parent. 


mov ah,0 ; function number 
int 2ih ; transfer to MS-DOS 
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Int 21H [1.0] 
Function 01H 
Character input with echo 


[1] Inputs a character from the keyboard, then echoes it to the display. If no character is ready, waits until 
one is available. 


[2.0+] Reads a character from the standard input device and echoes it to the standard output device. If no 
character is ready, waits until one is available. Input can be redirected. (If input has been redirected, 
there is no way to detect EOF.) 


Call with: AH = 01H 
Returns: AL = 8-bit input data 
Notes: = If the standard input is not redirected, and the character read is a Ctrl-C, an Int 23H 


is executed. If the standard input is redirected, a Ctrl-C is detected at the console, 
and BREAK is ON, an Int 23H is executed. 

= To read extended ASCII codes (such as the special function keys F1 to F10) on the 
IBM PC and compatibles, you must call this function twice. The first call returns the 
value 00H to signal the presence of an extended cade. 

= See also Int 21H Functions 06H, 07H, and 08H, which provide character input with 
various combinations of echo and/or Ctrl-C sensing. 

m (2.0+] You can also read the keyboard by issuing a read (Int 21H Function 3FH) using 
the predefined handle for the standard input (0000H), if input has not been redi- 
rected, or a handle obtained by opening the logical device CON. 


Example: Read one character from the keyboard into register AL, echo it to the display, and store it 
in the variable char. 


char db 0 ; input character 
mov ah,l : function number 
int 21h > transfer to MS-DOS 
mov char,al ; save character 
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SE 
Int 21H [1.0] 


Function 02H 
Character output 


[1] Outputs a character to the currently active video display. 


[2.0+] Outputs a character to the standard output device. Output can be redirected. (If output is redi- 
rected, there is no way to detect disk full.) 


Call with: AH = 02H 
DL = 8-bit data for output 


Returns: Nothing 


Notes: = Ifa Ctrl-C is detected at the keyboard after the requested character is output, an 
Int 23H is executed. 
= Ifthe standard output has not been redirected, a backspace code (08H) causes the 
cursor to move left one position. If output has been redirected, the backspace code 
does not receive any special treatment. 


# [2.0+] You can also send strings to the display by performing a write (Int 21H Func- 
tion 40H) using the predefined handle for the standard output (0001H), if output has 
not been redirected, or a handle obtained by opening the logical device CON. 


Example: Send the character “«” to the standard output device. 


mov ah,2 ; function number 


mov dj,‘«' ; Character to output 
int 21h ; transfer to MS-DOS 


Int 21H [1.0] 
Function 03H 


Auxiliary input 
[1] Reads a character from the first serial port. 


[2.0+] Reads a character from the standard auxiliary device. The default is the first serial port (COMI). 


Call with: AH = 03H 
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ae 


Returns: AL = 8-bit input data 


a 


Notes: ™ In most MS-DOS systems, the serial device is unbuffered and is not interrupt-driven. 
If the auxiliary device sends data faster than your program can process it, characters 
may be lost. 


™ At startup on the IBM PC, PC-DOS initializes the first serial port to 2400 baud, no 
parity, 1 stop bit, and 8 data bits. Other implementations of MS-DOS may initialize 
the serial device differently. 


® There is no way for a user program to read the status of the auxiliary device or to 
detect I/O errors (such as lost characters) through this function call. On the IBM PC, 
more precise control can be obtained by calling ROM BIOS Int 14H or by driving the 
communications controller directly. 

™ Ifa Ctrl-C is detected at the keyboard, an Int 23H is executed. 


= (2.0+] You can also input from the auxiliary device by requesting a read (Int 21H 
Function 3FH) using the predefined handle for the standard auxiliary device 
(0003H) or using a handle obtained by opening the logical device AUX. 


$$ 


Example: —_ Read a character from the standard auxiliary input and store it in the variable char. 


char db 0 ; input character 
mov ah,3 ; function number 
int 21h : transfer to MS-DOS 
mov char,al s save character 


Int 21H [1.0] 
Function 04H 


Auxiliary output 


[1] Outputs a character to the first serial port. 


(2.0+] Outputs a character to the standard auxiliary device. The default is the first serial port CCOMD). 


Call with: AH = 04H 
DL = 8-bit data for output 


Returns: Nothing 
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Notes: _ © Ifthe output device is busy, this function waits until the device is ready to accept a 
character. 


= There is no way to poll the status of the auxiliary device using this function. On the 
IBM PC, more precise control can be obtained by calling ROM BIOS Int 14H or by 
driving the communications controller directly. ” 


m Ifa Ctrl-C is detected at the keyboard, an Int 23H is executed. 


= [2.0+] You can also send strings to the auxiliary device by performing a write (int 
21H Function 40H) using the predefined handle for the standard auxiliary device 
(0003H) or using a handle obtained by opening the logical device AUX. 


Example: Output a “«” character to the auxiliary device. 


mov ah,4 : function number 


mov dj,‘«' ; Character to output 
int 2ih ; transfer to MS-DOS 


Se 
Int 21H [1.0] 


Function 05H 


Printer output 


a 
[1] Sends a character to the first list device (PRN or LPT1). 


[2.0+] Sends a character to the standard list device. The default device is the printer on the first parallel 
port (LPT1), unless explicitly redirected by the user with the MODE command. 


Call with: AH = 05H 
DL = 8-bit data for output 


Returns: Nothing 


nh 
Notes: ™ Ifthe printer is busy, this Function waits until the printer is ready to accept the 


character. 
m There is no standardized way to poll the status of the printer under MS-DOS. 
m Ifa Ctrl-C is detected at the keyboard, an Int 23H is executed. 


= [2.0+] You can also send strings to the printer by performing a write (Int 21H 
Function 40H) using the predefined handle for the standard printer device (0004H) 
or using a handle obtained by opening the logical device PRN or LPT1. 
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a a a SS SSS eee 


Example: Output the character “+” to the list device. 


mov ah,5 : function number 


mov dj,‘*' ; character to output 
int 21h - transfer to MS-DOS 


Int 21H | [1.0] 
Function 06H 
Direct console I/O 


a en a 


Used by programs that need to read and write all possible characters and control codes without any inter- 
ference from the operating system. 


[1] Reads a character from the keyboard or writes a character to the display. 


[2.0+] Reads a character from the standard input device or writes a character to the standard output 
device. I/O may be redirected. (If I/O has been redirected, there is no way to detect EOF or disk full.) 


nt 


Call with: AH = 06H 
DL = function requested 
OOH-FEH _ if output request 
OFFH if input request 


OO 


Returns: If called with DL = OOH—OFEH 


Nothing 

If called with DL = FFH and a character is ready 

Zero flag =clear 

AL = 8-bit input data 

If called with DL = FFH and no character is ready 

Zero flag = set 
a — 
Notes: = No special action is taken upon entry of a Ctrl-C when this service is used. 


m ‘To read extended ASCII codes (such as the special function keys F1 to F10) on the 
IBM PC and compatibles, you must call this function twice. The first call returns the 
value 00H to signal the presence of an extended code. 

= See also Int 21H Functions 01H, 07H, and 08H, which provide character input with 
various combinations of echo and/or Ctrl-C sensing, and Functions 02H and 09H, 
which may be used to write characters to the standard output. 
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= [2.0+] You can also read the keyboard by issuing a read (Int 21H Function 3FH) using 
the predefined handle for the standard input (OOOOH), if input has not been redi- 
rected, or a handle obtained by opening the logical device CON. 

@ [2.0+] You can also send characters to the display by issuing a write (Int 21H Func- 
tion 40H) using the predefined handle for the standard output (0001H), if output has 
not been redirected, or a handle obtained by opening the logical device CON. 


Examples: Send the character “*” to the standard output device. 


mov ah,6 ; function number 


mov dj,'*' ; Character to output 
int 2ih ; transfer to MS-DOS 


Read a character from the standard input device and save it in the variable char. If no 
character is ready, wait until one is available. 


char db 0 ; input character 

wait: mov ah,6 ; function number 
mov d1,0ffh ; parameter for read 
int 2ih ; transfer to MS-DOS 
jz wait ; wait until char ready 
mov char,al >; save the character 


————— 
Int 21H | [1.0] 


Function 07H 
Unfiltered character input without echo 


[1] Reads a character from the keyboard without echoing it to the display. If no character is ready, waits 
until one is available. 


[2.0+] Reads a character from the standard input device without echoing it to the standard output device. 
If no character is ready, waits until one is available. Input may be redirected. (If input has been redi- 
rected, there is no way to detect EOF.) 
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Returns: AL = §-bit input data 
NN 
Notes: ™ No special action is taken upon entry of a Ctrl-C when this function is used. If Ctrl-C 


checking is required, use Int 21H Function 08H instead. 

™ To read extended ASCII codes (such as the special function keys F1 to F10) on the 
IBM PC and compatibles, you must call this function twice. The first call returns the 
value 00H to signal the presence of an extended code. 

™ See also Int 21H Functions 01H, 06H, and 08H, which provide character input with 
various combinations of echo and/or Ctrl-C sensing. 

@ [2.0+] You can also read the keyboard by issuing a read (int 21H Function 3FH) using 
the predefined handle for the standard input (0000H), if input has not been redi- 
rected, or a handle obtained by opening the logical device CON. 


NN — 
Example: Read a character from the standard input without echoing it to the display, and store it in 
the variable char. 


char db 0 ; input character 
mov ah,/7 - function number 
int 21h > transfer to MS-DOS 
mov char,al ; save character 


aT 


Int 21H [1.0] 
Function 08H 
Character input without echo 


A a 


[1] Reads a character from the keyboard without echoing it to the display. If no character is ready, waits 
until one is available. 


(2.0+] Reads a character from the standard input device without echoing it to the standard output device. 
If no character is ready, waits until one is available. Input may be redirected. (If input has been redi- 
rected, there is no way to detect EOF.) 


Call with: AH = 08H 


a 


Returns: AL = 8-bit input data 
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Notes: = Ifthe standard input is not redirected, and the character read is a Ctrl-C, an Int 23H 
is executed. If the standard input is redirected, a Ctrl-C is detected at the console, 
and BREAK is ON, an Int 23H is executed. To avoid possible interruption by a Ctrl-C, 
use Int 21H Function 07H instead. 

= To read extended ASCII codes (such as the special function keys F1 to F10) on the 
IBM PC and compatibles, you must call this function twice. The first call returns the 
value 00H to signal the presence of an extended code. 


w See also Int 21H Functions 01H, 06H, and 07H, which provide character input with 
various combinations of echo and/or Ctrl-C sensing. 


@ [2.0+] You can also read the keyboard by issuing a read (Int 21H Function 3FH) using 
the predefined handle for the standard input (0000H), if input has not been redi- 
rected, or a handle obtained by opening the logical device CON. 


eee 
Example: Read a character from the standard input without echoing it to the display, allowing pos- 
sible detection of Ctrl-C, and store the character in the variable char. 


char db 0 
mov ah,8 ; function number 
int 21h ; transfer to MS-DOS 
mov char,al ; save character 


—— 
Int 21H [1.0] 


Function 09H 
Display string 


[1] Sends a string of characters to the display. 


[2.0+] Sends a string of characters to the standard output device. Output may be redirected. (If output has 
been redirected, there is no way to detect disk full.) 


a 
Call with: AH = 09H 


DS:DX = segment:offset of string 


Se 
Returns: Nothing 
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NN 
Notes: = The string must be terminated with the character $ (24H), which is not transmitted. 
Any other ASCII codes, including control codes, can be embedded in the string. 
= See Int 21H Functions 02H and 06H for single-character output to the video display 
or standard output device. 
If a Ctrl-C is detected at the keyboard, an Int 23H is executed. 
[2.0+] You can also send strings to the display by performing a write (int 21H Func- 
tion 40H) using the predefined handle for the standard output (0001H), if it has not 
been redirected, or a handle obtained by opening the logical device CON. 


I OO 
Example: ~ Send the string Hello World, followed by a carriage return and line feed, to the standard 
output device. 
cr equ Odh 
lf equ Oah 
msg db "Hello World’,cr,1f,'$' 
mOV ah,9 ; function number 
mov dx,seg msg : address of string 
mov ds,dx 
mov dx,offset msg 
int 2ih - transfer to MS-DOS 


Int 21H [1.0] 
Function 0AH (10) 
Buffered keyboard input 


2... 


[1] Reads a line from the keyboard and places it in a user-designated buffer. The characters are echoed to 
the display. 


[2.0+] Reads a string of bytes from the standard input device, up to and including an ASCII carriage return 
(ODH), and places them in a user-designated buffer. The characters are echoed to the standard output 
device. Input may be redirected. (If input has been redirected, there is no way to detect EOF.) 


Call with: AH = 0AH 
DS:DX = segment:offset of buffer 


ae ee 
Returns: Nothing (data placed in buffer) 
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Notes: = The buffer used by this function has the following format: 
Byte Contents 


0 maximum number of characters to read, set by program 

1 number of characters actually read (excluding carriage return), set 
by MS-DOS 

2+ string read from keyboard or standard input, terminated by a carriage 
return (ODH) 


@ If the buffer fills to one fewer than the maximum number of characters it can hold, 
subsequent input is ignored and the bell is sounded until a Carriage return is 
detected. 

= This input function is buffered with type-ahead capability, and all of the standard 
keyboard editing commands are active. 

™ Ifthe standard input is not redirected, and a Ctrl-C is detected at the console, an 
Int 23H is executed. If the standard input is redirected, a Ctrl-C is detected at the 
console, and BREAK is ON, an Int 23H is executed. 

@ See Int 21H Functions 01H, 06H, 07H, and 08H for single-character input from the 
keyboard or standard input device. 

@ [2.0+] You can also read strings from the keyboard by performing a read (Int 21H 
Function 3FH) using the predefined handle for the standard input (O000H), if it has 
not been redirected, or a handle obtained by opening the logical device CON. 


Example: Read a string that is a maximum of 80 characters long from the standard input device, 
placing it in the buffer named buff. 


buff db 81 >; Maximum length of input 
db 0 > actual length of input 
db 81 dup (0) ; actual input placed here 
mov ah,0ah ; function number 
mov dx,seg buff ; input buffer address 
mov ds,dx 
mov dx,offset buff 
int 2ih ; transfer to MS-DOS 
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a SS 


Int 21H [1.0] 
Function OBH (11) 
Check input status 


a 
[1] Checks whether a character is available from the keyboard. 


[2.0+] Checks whether a character is available from the standard input device. Input can be redirected. 


a 


Call with: AH = 0BH 
NN. 
Returns: AL = QOH if no character is available 


FFH if at least one character is available 


Ba cs 
Notes: m [1] If a Ctrl-C is detected, an Int 23H is executed. 
= (2.0+] If the standard input is not redirected, and a Ctrl-C is detected at the console, 
an Int 23H is executed. If the standard input is redirected, a Ctrl-C is detected at the 
console, and BREAK is ON, an Int 23H is executed. 
m= Ifa character is waiting, this function will continue to return a true flag until the 
character is consumed with a call to Int 21H Function 01H, 06H, 07H, 08H, OAH, 
or 3FH. 
@ This function is equivalent to IOCTL Int 21H Function 44H Subfunction 06H. 


OOOO 


Example: Test whether a character is available from the standard input. 


mov ah, Obh ; function number 

int 21h ; transfer to MS-DOS 
or al,al ; character waiting? 
jnz ready ; jump if char ready 


a 


Int 21H [1.0] 
Function OCH (12) 
Flush input buffer and then input 


ee 
1] Clears the type-ahead buffer and then invokes one of the keyboard input functions. 


[2.0+] Clears the standard input buffer and then invokes one of the character input functions. Input can 
be redirected. 


MS-DOS Functions Reference 353 


Call with: AH = 0CH 


AL = number of input function to be invoked after resetting buffer (must be 
01H, 06H, 07H, 08H, or OAH) 

Gf AL = OAH) 

DS:DX = segment:offset of input buffer 


Returns: Gf called with AL = 01H, 06H, 07H, or 08H) 
AL = 8-bit input data 
Gf called with AL = OAH) 
Nothing (data placed in buffer) 


Notes: m The function exists to allow a program to defeat MS-DOS’s type-ahead feature. It 
discards any characters that are waiting in MS-DOS’s internal type-ahead buffer, 
forcing the specified input function to wait for a character (usually a keyboard entry) 
that is truly entered after the program’s request. 

m The presence or absence of Ctrl-C checking during execution of this function 
depends on the function number placed in register AL. 

= A function number in AL other than 01H, 06H, 07H, 08H, or OAH simply flushes the 
input buffer and returns control to the calling program. 


5 a se Se 
Example: Clear the type-ahead buffer, then wait for a character to be entered, echoing it and then 
returning it in AL. Store the character in the variable char 


char db 0 
mov ah,Och ; function number 
mov al,l ; subfunction = input char 
int 21h ; transfer to MS-DOS 
mov char,al ; save character 


SE ee 
Int 21H [1.0] 


Function 0DH (13) 
Disk reset 


Flushes all file buffers. All data that has been logically written by user programs, but has been temporarily 
buffered within MS-DOS, is physically written to the disk. 


I a ee es 
Call with: AH = 0DH 
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Returns: Nothing 


eS 

Notes: = This function does not update the disk directory for any files that are still open. If 
your program fails to properly close all files before the disk is removed, and files 
have changed size, the data forced out to the disk by this function may still be inac- 
cessible because the directory entries will not be correct. 


= (3.3+] Int 21H Function 68H (Commit File) should be used in preference to this func- 
tion, since it also updates the disk directory. 


a 


Example: Flush all MS-DOS internal disk buffers. 


mov ah,Odh ; function number 
int 21h : transfer to MS-DOS 


Int 21H [1.0] 
Function OEH (14) 
Select disk 


Se 


Selects the specified drive to be the current, or default, disk drive and returns the total number of logical 
drives in the system. 


Call with: AH = 0EH 
DL = drive code (0 = A, 1 = B, etc.) 
Returns: AL = number of logical drives in system 
Notes: w [1] 16 drive designators (0 through OFH) are available. 
= [2] 63 drive designators (0 through 3FH) are available. 
= [3.0+] 26 drive designators (0 through 19H) are available. 
= 


To preserve upward compatibility, new applications should limit themselves to the 
drive letters A~Z (0 = A, 1 = B, etc.). 


= Logical drives means the total number of block devices: floppy disks, simulated disk 
drives (RAMdisks), and hard-disk drives. A single physical hard-disk drive is fre- 
quently partitioned into two or more logical drives. 

= (1) (2] In single-drive IBM PC-compatible systems, the value 2 is returned in AL, 
because PC-DOS supports two logical drives (A: and B:) on the single physical 
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floppy-disk drive. The actual number of physical drives in the system can be deter- 
mined with ROM BIOS Int 11H. 

= [3.0+] The value returned in AL is either 5 or the drive code corresponding to the 
LASTDRIVE entry Cif any) in CONFIG.SYS, whichever is greater. 


Example: — Make drive B the current (default) disk drive. Save the total number of logical drives in 
the system in the variable drives. 


drives db 0 
mov ah,Qeh ; function number 
mov dj,l ; drive 1=8 
int 21h ; transfer to MS-DOS 
mov drives,al ; Save total drives 


———— 
Int 21H [1.0] 


Function OFH (15) 


Open file 
eee 


Opens a file and makes it available for subsequent read/write operations. 


Se 


Call with: AH = OFH 
DS:DX = segment:offset of file control block 


Returns: If function successful (file found) 


AL = 00H 
and FCB filled in by MS-DOS as follows: 
drive field (offset OOH) = 1 for drive A, 2 for drive B, etc. 
current block field (offsetOCH) =O0OH 
record size field (offset OEH) = 0O80H 
[2.0+] size field (offset 10H=D = file size from directory 
[2.0+] date field (offset 14H) = date stamp from directory 
[2.0+] time field (offset 16H) = time stamp from directory 
If function unsuccessful (file not found) 
AL = OFFH 
Notes: ™ If your program is going to use a record size other than 128 bytes, it should set the 


record-size field at FCB offset OEH after the file is successfully opened and before 
any other disk operation. 
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™ If random access is to be performed, the calling program must also set the FCB 
relative-record field (offset 21H) after successfully opening the file. 


@ For format of directory time and date, see Int 21H Function 57H. 


® (2.0+] Int 21H Function 3DH, which allows full access to the hierarchical directory 
structure, should be used in preference to this function. 


® [3.0+] If the program is running on a network, the file is opened for read/write 
access in compatibility sharing mode. 


a 


Example: Attempt to open the file named QUACK.DAT on the default disk drive. 


myfcb db 0 ; drive = default 
db "QUACK : ; filename, 8 characters 
db *DAT' ; extension, 3 characters 
db 25 dup (0) ; remainder of FCB 
mov ah, Ofh ; function number 
mov dx,seg myfcb : address of FCB 
mov ds ,dx 
mov dx,offset myfcb 
int 21h ; transfer to MS-DOS 
or al,al ; check status 
jnz error ; jump if open failed 


Int 21H [1.0] 
Function 10H (46) 
Close file 


Closes a file, flushes all MS-DOS internal disk buffers associated with the file to disk, and updates the disk 
directory if the file has been modified or extended. 


Call with: AH = 10H 
DS:DX = segment:offset of file control block 
Returns: If function successful (directory update successful) 
AL = 00H 
If function unsuccessful (file not found in directory) 
AL = FFH 
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Notes: = [1] [2] MS-DOS versions 1 and 2 do not reliably detect a floppy-disk change, and an 
error can occur if the uset.changes disks while a file is still open on that drive. In the 
worst case, the directory and file allocation table of the newly inserted disk can be 
damaged or destroyed. 


m [2.0+] Int 21H Function 3EH should be used in preference to this function. 


Example: Close the file that was previously opened using the file control block named myfcb. 


myfcb db 0 ; drive = default 
db "QUACK =! ; filename, 8 characters 
db *DAT' ; extension, 3 characters 
db 25 dup (0) ; remainder of FCB 
mov ah,10h ; function number 
mov dx,seg myfcb ; address of FCB 
mov ds ,dx 
mov dx,offset myfcb 
int 2ih ; transfer to MS-DOS 
or al,al ; check status 
jnz error ; jump if close failed 


—$———— 
Int 21H [1.0] 


Function 11H (17) 
Find first file 


Searches the current directory on the designated drive for a matching filename. 


Call with: AH = 11H 
DS:DX = segment:offset of file control block 
Returns: If function successful (matching filename found) 
AL = 00H 


and buffer at current disk transfer area (DTA) address filled in as an unopened normal 
FCB or extended FCB, depending on which type of FCB was input to function 


If function unsuccessful (no matching filename found) 
AL = FFH 
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a 


= Use Int 21H Function 1AH to set the DTA to point to a buffer of adequate size before 
calling this function. 


Notes: 


® The wildcard character ? is allowed in the filename in all versions of MS-DOS. In ver- 
sions 3.0 and later, the wildcard character « may also be used in a filename. If? or + 
is used, this function returns the first matching filename. 


= An extended FCB must be used to search for files that have the system, hidden, read- 
only, directory, or volume-label attributes. 


= If an extended FCB is used, its attribute byte determines the type of search that will 
be performed. If the attribute byte contains 00H, only ordinary files are found. If the 
volume-label attribute bit is set, only volume labels will be returned (if any are pres- 
ent). If any other attribute or combination of attributes is set (such as hidden, system, 
or read-only), those files and all ordinary files will be matched. 


m (2.0+] Int 21H Function 4EH, which allows full access to the hierarchical directory 
structure, should be used in preference to this function. 


Example: 


Search for the first file with the extension .COM in the current directory. 


buff db 


myfcb db 
db 
db 
db 


mov 
mov 
mov 
mov 
int 


mov 
mov 
mov 
mov 
int 
or 

jnz 


37 dup (0) 


0 
"COM" 
25 dup (0) 


ah,lah 

dx,seg buff 

ds ,dx 
dx,offset buff 
21h 


ah,1lh 

dx,seg myfcb 

ds ,dx 

dx,offset myfcb 
21h 

al,al 

error 


receives search result 


drive = default 
wildcard filename 
extension = COM 


; remainder of FCB 


set DTA address 
function number 
buffer address 


transfer to MS-DOS 


search for first match 
function number 


; address of FCB 


transfer to MS-DOS 
check status 
jump if no match 
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SEE 
Int 21H [1.0] 


Function 12H (18) 
Find next file 
pr 


Given that a previous call to Int 21H Function 11H has been successful, returns the next matching file- 
name Cif any). 


Call with: AH = 12H 
DS:DX = segment:offset of file control block 
Returns: If function successful (matching filename found) 
AL = 00H 


and buffer at current disk transfer area (DTA) address set up as an unopened normal 
FCB or extended FCB, depending on which type of FCB was originally input to Int 21H 


Function 11H 

If function unsuccessful (no more matching filenames found) 

AL = FFH 
nh st, 
Notes: = This function assumes that the FCB used as input has been properly initialized by a 


previous call to Int 21H Function 11H (and possible subsequent calls to Int 21H 
Function 12H) and that the filename or extension being searched for contained at 
least one wildcard character. 


® As with Int 21H Function 11H, it is important to use Int 21H Function 1AH to set the 
DTA to a buffer of adequate size before calling this function. 


@ = [2.0+] Int 21H Functions 4EH and 4FH, which allow full access to the hierarchical 
directory structure, should be used in preference to this function. 


i 
Example: Assuming a previous successful call to function 11H, search for the next file with the 


extension .COM in the current directory. If the DTA has not been changed since the 
previous search, another call to Function 1AH is not necessary. 


buf f db 37 dup (0) ; receives search result 
my_fcb db 0 ; drive = default 

db 272227222" ; wildcard filename 

db *COM' ; extension = COM 

db 25 dup (0) ; remainder of FCB 
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> set DTA address 


mov ah, lah ; function number 
mov dx,seg buff : buffer address 

mov ds ,dx 

mov dx,offset buff 

int 21h ; transfer to MS-DOS 


: search for next match 


mov ah,12h ; function number 
mov dx,seg myfcb ; address of FCB 

mov ds,dx 

mov dx,offset myfcb 

int 21h ; transfer to MS-DOS 
or al,al ; check status 

jnz error ; jump if no match 


Int 21H [1.0] 
Function 13H (9) 
Delete file 


Deletes all matching files from the current directory on the default or specified disk drive. 


Call with: AH = 13H 

DS:DX = segment:offset of file control block 
Returns: If function successful Cfile or files deleted) 

AL = 00H 


If function unsuccessful (no matching files were found, or at least one matching file 
was read-only) 


AL = FFH 
Notes: w The wildcard character ? is allowed in the filename; if ? is present and there is more 


than one matching filename, all matching files will be deleted. 


w (2.0+] Int 21H Function 41H, which allows full access to the hierarchical directory 
structure, should be used in preference to this function. 


m (3.0+] If the program is running on a network, the user must have Create rights to 
the directory containing the file to be deleted. 
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Example: Delete the file MYFILE.DAT from the current disk drive and directory. 


myfcb db 


0 ; drive = default 
*MYFILE ' ; filename, 8 chars 
*DAT' ; extension, 3 chars 
25 dup (0) ; remainder of FCB 
ah,13h ; function number 
dx,seg myfcb ; address of FCB 

ds ,dx 

dx,offset myfcb 

21h ; transfer to MS-DOS 
al,al ; check status 

error ; jump, delete failed 


Int 21H 


Function 14H (20) 


Sequential read 


[1.0] 


Reads the next sequential block of data from a file, then increments the file pointer appropriately. 


Call with: AH 


= 14H 


DS:DX = segment:offset of previously opened file control block 
Returns: AL = 00H if read successful 
01H if end of file 
02H if segment wrap 
03H if partial record read at end of file 
Notes: ™ The record is read into memory at the current disk transfer area (DTA) address, 


specified by the most recent call to Int 21H Function 1AH. If the size of the record 
and the location of the buffer are such that a segment overflow or wraparound would 
occur, the function fails with a return code of 02H. 

= The number of bytes of data to be read is specified by the record-size field (offset 
OEH) of the file control block (FCB). 

m The file location of the data that will be read is specified by the combination of the 
current block field (offset OCH) and current record field (offset 20H) of the file con- 
trol block (FCB). These fields are also automatically incremented by this function. 
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® Ifa partial record is read at the end of file, it is padded to the requested record length 


with zeros. 


= (3.0+] If the program is running on a network, the user must have Read access rights 
to the directory containing the file to be read. 


Example: 


Read 1024 bytes of data from the file specified by the previously opened file control 


block myfcb. 


myfcb 


0 ; drive = default 
"QUACK / ; filename, 8 chars 
"DAT" ; extension, 3 chars 
25 dup (0) ; remainder of FCB 
ah,14h ; function number 
dx,seg myfcb ; address of FCB 
ds,dx 


dx,offset myfcb 
; set record size 
word ptr myfcb+0eH,1024 


21h ; transfer to MS-DOS 
al,al ; check status 
error ; jump if read failed 


Int 21H 
Function 15H (21) 
Sequential write 


[1.0] 


Writes the next sequential block of data into a file, then increments the file pointer appropriately. 


Call with: 


Returns: 


Notes: 


AH 
DS:DX 


AL 


= 15H 
= segment:offset of previously opened file control block 


= 0OH if write successful 
01H if disk is full 
02H if segment wrap 


= The record is written (logically, not necessarily physically) to the disk from memory 
at the current disk transfer area (DTA) address, specified by the most recent call to 
Int 21H Function 1AH. If the size of the record and the location of the buffer are such 
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that a segment overflow or wraparound would occur, the function fails with a return 


code of 02H. 


=" The number of bytes of data to be written is specified by the record-size field (offset 
OEH) of the file control block (FCB). 


= The file location of the data that will be written is specified by the combination of 
the current block field (offset OCH) and current record field (offset 20H) of the file 
control block (FCB). These fields are also automatically incremented by this 


function. 


= (3.0+] If the program is running on a network, the user must have Write access rights 
to the directory containing the file to be written. 


Example: = Write 1024 bytes of data to the file specified by the previously opened file control block 


myfcb. 

myfcb db 0 ; 
db "QUACK = ; 
db "DAT’ : 
db 25 dup (0) ; 


mov ah,15h 


drive = default 
filename, 8 chars 
extension, 3 chars 
remainder of FCB 


function number 


mov dx,seg myfcb ; address of FCB 
mov ds,dx 
mov dx,offset myfcb 
; set record size 
mov word ptr myfcbt+0eh,1024 
int 2ih ; transfer to MS-DOS 
or al,al ; check status 
jnz error ; jump if write failed 


Int 21H 
Function 16H (22) 
Create file 


[1.0] 


Creates a new directory entry in the current directory or truncates any existing file with the same name to 
zero length. Opens the file for subsequent read/write operations. 


Call with: AH = 16H 


DS:DX = segment:offset of unopened file control block 
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Returns: 


If function successful (file was created or truncated) 


AL = 00H 

and FCB filled in by MS-DOS as follows: 

drive field (offset OOH) = 1 for drive A, 2 for drive B, etc. 
current block field (offset OCH) = OOH 

record size field (offset OEH) = 0080H 

[2.0+] size field (offset 10H) = file size from directory 

[2.0+] date field (offset 14H) = date stamp from directory 
[2.0+] time field (offset 16H) = time stamp from directory 

If function unsuccessful (directory full) 

AL = FFH 


Notes: 


Example: 


m Since an existing file with the specified name is truncated to zero length (ie., all data 
in that file is irretrievably lost), this function must be used with caution. 


m If this function is called with an extended file control block (FCB), the new file may 
be assigned a special attribute, such as hidden or system, during its creation by set- 
ting the appropriate bit in the extended FCB’s attribute byte. 


m Since this function also opens the file, a subsequent call to Int 21H Function OFH is 
not required. 


For format of directory time and date, see Int 21H Function 57H. 


[2.0+] Int 21H Functions 3CH, 5AH, 5BH, and 6CH, which provide full access to the 
hierarchical directory structure, should be used in preference to this function. 


= [3.0+] If the program is running on a network, the user must have Create rights to 
the directory that will contain the new file. 


Create a file in the current directory using the name in the file control block myfcb. 


myfcb db 0 ; drive = default 
db *QUACK ; ; filename, 8 chars 
db *DAT' ; extension, 3 chars 
db 25 dup (0) ; remainder of FCB 
mov ah,1l6h ; function number 
mov dx,seg myfcb ; address of FCB 
mov ds,dx 
mov dx,offset myfcb 
int 21h ; transfer to MS-DOS 
or al,al ; check status 
jnz error ; jump if create failed 
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Int 21H [1.0] 
Function 17H (23) 
Rename file 


Alters the name of all matching files in the current directory on the disk in the specified drive. 


Call with: AH = 17H | 
DS:DX = segment:offset of “special” file control block 


Returns: If function successful (one or more files renamed) 
AL = 00H 


If function unsuccessful (no matching files, or new filename matched an existing file) 
AL = FFH 


Notes: ® The special file control block has a drive code, filename, and extension in the usual 
position (bytes 0 through OBH) and a second filename starting 6 bytes after the first 
(offset 11H). 


@ The ? wildcard character can be used in the first filename. Every file matching the 
first file specification will be renamed to match the second file specification. 


™ If the second file specification contains any ? wildcard characters, the corresponding 
letters in the first filename are left unchanged. 


= The function terminates if the new name to be assigned to a file matches that of an 
existing file. 


@ [2.0+] An extended FCB can be used with this function to rename a directory. 


@ [2.0+] Int 21H Function 56H, which allows full access to the hierarchical directory 
structure, should be used in preference to this function. 


Example: Rename the file OLDNAME.DAT to NEWNAME.DAT. 


myfcb db 0 ; drive = default 
db "OLDNAME ' ; old file name, 8 chars 
db ‘DAT’ ; old extension, 3 chars 
db 6 dup (0) ; reserved area 
db "NEWNAME ' ; new file name, 8 chars 
db *DAT’ ; new extension, 3 chars 
db 14 dup (0) ; reserved area 
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mov ah,17h ; function number 


mov dx,seg myfcb ; address of FCB 

mov ds,dx 

mov dx,offset myfcb 

int 21h ; transfer to MS-DOS 
or al,al ; check status 


jnz error ; jump if rename failed 


Int 21H 
Function 18H (24) 
Reserved 


Int 21H [1.0] 
Function 19H (25) 
Get current disk 


Returns the drive code of the current, or default, disk drive. 


Call with: AH = 19H 
Returns: AL = drive code (0 = A, 1 = B, etc.) 
Notes: ® To set the default drive, use Int 21H Function OEH. 


=@ Some other Int 21H functions use drive codes beginning at 1 (that is, 1 = A, 2 = B, 
etc.) and reserve drive code zero for the default drive. 


Example: Get the current disk drive and save the code in the variable cdrive. 


cdrive db 0 ; current drive code 
mov ah,19h ; function number 
int 21h ; transfer to MS-DOS 
MOV cdrive,al ; save drive code 
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Int 21H [1.0] 
Function 1AH (26) 
Set DTA address 


Specifies the address of the disk transfer area (DTA) to be used for subsequent FCB-related function calls. 


Call with: AH = 1AH 


DS:DX = segment:offset of disk transfer area 


Returns: Nothing 


Notes: = If this function is never called by the program, the DTA defaults to a 128-byte buffer 
at offset 0080H in the program segment prefix. 


= In general, it is the programmer’s responsibility to ensure that the buffer area speci- 
fied is large enough for any disk operation that will use it. The only exception to this 
is that MS-DOS will detect and abort disk transfers that would cause a segment wrap. 


Int 21H Function 2FH can be used to determine the current disk transfer address. 


The only handle-type operations that rely on the DTA address are the directory 
search functions, Int 21H Functions 4EH and 4FH. 


Example: Set the current disk transfer area address to the buffer labeled buff. 


buff db 128 dup (7?) 
mov ah,lah ; function number 
mov dx,seg buff 5 address of disk 
mov ds,dx ; transfer area 
mov dx,offset buff 
int 21h ; transfer to MS-DOS 


Int 21H [1.0] 
Function 1BH (27) 
Get default drive data 


Obtains selected information about the default disk drive and a pointer to the media identification byte 
from its file allocation table. 
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Call with: AH = 1BH 


Returns: If function successful 
AL = sectors per cluster 
DS:BX = segment:offset of media ID byte 
CX = size of physical sector (bytes) 
DX = number of clusters for default drive 
If function unsuccessful (invalid drive or critical error) 
AL = FFH 
Notes: ® The media ID byte has the following meanings: 
OFOH  3.5-inch double-sided, 18 sectors 
| or “other” 


OF8H fixed disk 

OFOH  5.25-inch double-sided, 15 sectors 
or 3.5-inch double-sided, 9 sectors 

OFCH 5.25-inch single-sided, 9 sectors 

OFDH  5.25-inch double-sided, 9 sectors 

OFEH 5.25-inch single-sided, 8 sectors 

OFFH  5.25-inch double-sided, 8 sectors 


® To obtain information about disks other than the one in the default drive, use 
Int 21H Function 1CH or 36H. 


® [1] The address returned in DS:BX points to a copy of the first sector of the actual 
FAT, with the media ID byte in the first byte. 


= (2.0+] The address returned in DS:BX points only to a copy of the media ID byte 
from the disk’s FAT; the memory above that address cannot be assumed to contain 
the FAT or any other useful information. If direct access to the FAT is required, use 
Int 25H to read it into memory. 


Example: _ Determine whether the current disk drive is fixed or removable. 


mov ah,lbh ; function number 
int 21h ; transfer to MS-DOS 


; check media ID byte 
cmp byte ptr [bx],0f8h 
je fixed ; jump if fixed disk 
jmp floppy ; else assume floppy 
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Int 21H [2.0] 
Function 1CH (28) 
Get drive data 


Obtains allocation information about the specified disk drive and a pointer to the media identification 
byte from its file allocation table. 


Call with: AH = 1CH 

DL = drive code (0 = default, 1 = A, etc.) 
Returns: If function successful 

AL = sectors per cluster 

DS:BX = segment:offset of media ID byte 

CX = size of physical sector (bytes) 

Dx = number of clusters for default or specified drive 

If function unsuccessful (invalid drive or critical error) 

AL = FFH 
a a ee ee 
Notes: = The media ID byte has the following meanings: 

OFOH  3.5-inch double-sided, 18 sectors 
or “other” 


OF8H fixed disk 

OF9H 5.25-inch double-sided, 15 sectors 
or 3.5-inch double-sided, 9 sectors 

OFCH  5.25-inch single-sided, 9 sectors 

OFDH = 5.25-inch double-sided, 9 sectors 

OFEH  5.25-inch single-sided, 8 sectors 

OFFH 5.25-inch double-sided, 8 sectors 


= In general, this call is identical to Int 21H Function 1BH, except for the ability to 
designate a specific disk drive. See also Int 21H Function 36H, which returns similar 
information. 

@ [1] The address returned in DS:BX points to a copy of the first sector of the actual 
FAT, with the media ID byte in the first byte. 

= [2.0+] The address returned in DS:BX points only to a copy of the media ID byte 
from the disk’s FAT; the memory above that address cannot be assumed to contain 
the FAT or any other useful information. If direct access to the FAT is required, use 
Int 25H to read it into memory. 
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Example: Determine whether disk drive C is fixed or removable. 


mov ah,lch > function number 
mov d1,3 > drive code 3 = C 
int 21h > transfer to MS-DOS 


; check media ID byte 
cmp byte ptr ds:[bx],0f8h 
je fixed ; jump if fixed disk 
jmp floppy ; else assume floppy 


Int 21H 
Function 1DH (29) 
Reserved 


Int 21H 
Function 1EH (30) 


Function 1FH (31) 
Reserved 


Int 21H 
Function 20H (32) 
Reserved 
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a en 
Int 21H | [1.0] 


Function 21H (33) 


Random read 
a ea ee a ee ee eee 


Reads a selected record from a file into memory. 


Call with: AH = 21H 
DS:DX = segment:offset of previously opened file control block 

Returns: AL = 00H if read successful 

01H if end of file 

02H if segment wrap, read canceled 

03H if partial record read at end of file 
meee 
Notes: ™ The record is read into memory at the current disk transfer area address, specified by 


the most recent call to Int 21H Function 1AH. It is the programmer’s responsibility to 
ensure that this area is large enough for any record that will be transferred. If the size 
and location of the buffer are such that a segment overflow or wraparound would 
occur, the function fails with a return code of 02H. 

= The file location of the data to be read is determined by the combination of the 
relative-record field (offset 21H) and the record-size field (offset OEH) of the FCB. 
The default record size is 128 bytes. 

® The current block field (offset OCH) and current record field (offset 20H) are up- 
dated to agree with the relative-record field as a side effect of the function. 

= The relative-record field of the FCB is not incremented by this function; it is the 
responsibility of the application to update the FCB appropriately if it wishes to read 
successive records. Compare with Int 21H Function 27H, which can read multiple 
records with one function call and automatically increments the relative-record field. 

= Ifa partial record is read at end of file, it is padded to the requested record length 
with zeros. 

@ (3.0+] If the program is running on a network, the user must have Read access rights 
to the directory containing the file to be read. 


SE a ae ee eee 
Example: Open the file MYFILE.DAT, set the record length to 1024 bytes, then read record number 
4 from the file into the buffer named buff. 


myfcb db 0 ; drive = default 
db "MYFILE ° ; filename, 8 chars 
db ‘DAT’ ; extension, 3 chars 
db 25 dup (0) ; remainder of FCB 
buff db 1024 dup (7?) ; receives read data 
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; open the file 


mov ah,Ofh ; function number 
mov dx,seg myfcb ; address of FCB 

mov ds ,dx 

mov dx,offset myfcb 

int 2ih ; transfer to MS-DOS 
or al,al ; check open status 
jnz error ; jump if no file 


: set DTA address 


mov ah, lah : function number 
mov dx,offset buff ; read buffer address 
int 21h : transfer to MS-DOS 


; set record size 
mov word ptr myfcb+0eh,1024 


; set record number 
mov word ptr myfcb+21h,4 
mov word ptr myfcbt+23h,0 


; read the record 


mov ah,21h ; function number 

mov dx,offset myfcb ; address of FCB 

int 2ih ; transfer to MS-DOS 
or al,al ; check status 

jnz error ; jump if read failed 


Int 21H [1.0] 
Function 22H (34) 
Random write 


Writes data from memory into a selected record in a file. 


Call with: AH = 22H 
DS:DX = segment:offset of previously opened file control block 
Returns: AL = 00H if write successful 
01H if disk full 
02H if segment wrap, write canceled 
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Notes: 


The record is written (logically, not necessarily physically) to the file from memory at 
the current disk transfer address, specified by the most recent call to Int 21H Func- 
tion 1AH. If the size and location of the buffer are such that a segment overflow or 
wraparound would occur, the function fails with a return code of 02H. 

The file location of the data to be written is determined by the combination of the 
relative-record field (offset 21H) and the record-size field (offset OEH) of the FCB. 
The default record size is 128 bytes. 

The current block field (offset OCH) and current record field (offset 20H) are up- 
dated to agree with the relative-record field as a side effect of the function. 

The relative-record field of the FCB is not incremented by this function; it is the 
responsibility of the application to update the FCB appropriately if it wishes to write 
successive records. Compare with Int 21H Function 28H, which can write multiple 
records with one function call and automatically increments the relative-record field. 
If a record is written beyond the current end of file, the space between the old end 
of file and the new record is allocated but not initialized. 

[3.0+] If the program is running on a network, the user must have Write access rights 
to the directory containing the file to be written. 


Example: 


374 


Open the file MYFILE.DAT, set the record length to 1024 bytes, write record number 4 
into the file from the buffer named buff, then close the file. 
myfcb db 0 ; drive = default 
db "MYFILE ' 3 filename, 8 chars 
db "DAT’ ; extension, 3 chars 
db 25 dup (0) ; remainder of FCB 
buff db 1024 dup (?) ; buffer for write 


Section IT 


; open the file 


mov ah,Ofh ; function number 
mov dx,seg myfcb ; address of FCB 

mov ds ,dx 

mov dx,offset myfcb 

int 21h ; transfer to MS-DOS 
or al,al ; check status 

jnz error ; jump if no file 


; set DTA address 


mov dx,offset buff ; buffer address 
mov ah,lah ; function number 
int 21h ; transfer to MS-DOS 


; set record size 
mov word ptr myfcbt0eh,1024 


; set record number 
mov word ptr myfcbt+21h,4 
mov word ptr myfcb+23h,0 


> write the record 


mov ah,22h ; function number 

mov dx,offset myfcb ; address of FCB 

int 21h ; transfer to MS-DOS 
or al,al ; check status 

jnz error ; jump if write failed 


: close the file 


mov ah,10h ; function number 

mov dx,offset myfcb ; address of FCB 

int 21h ; transfer to MS-DOS 
or al,al ; check status 

jnz error ; jump if close failed 


Int 21H [1.0] 
Function 23H (35) 
Get file size 


a 


Searches for a matching file in the current directory; if one is found, updates the FCB with the file’s size in 
terms of number of records. 


Call with: AH = 23H 

DS:DX = segment:offset of unopened file control block 
Returns: If function successful (matching file found) 

AL = 00H 


and FCB relative-record field (offset 21H) set to the number of records in the file, 
rounded up if necessary to the next complete record 


If function unsuccessful (no matching file found) 
AL = FFH 


a 


Notes: = An appropriate value must be placed in the FCB record-size field (offset OEH) before 
calling this function. There is no default record size for this function. Compare with 
the FCB-related open and create functions (Int 21H Functions OFH and 16H), which 
initialize the FCB for a default record size of 128 bytes. 

™ The record-size field can be set to 1 to find the size of the file in bytes. 
™ Because record numbers are zero based, this function can be used to position the 
FCB’s file pointer to the end of file. 
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eee 


Example: Determine the size in bytes of the file MYFILE.DAT and leave the result in registers 


DX:AX. 
myfcb db 0 ; drive = default 
db "MYFILE ' ; filename, 8 chars 
db ‘DAT’ ; extension, 3 chars 
db 25 dup (0) ; remainder of FCB 
mov ah,23h ; function number 
mov dx,seg myfcb ; address of FCB 
mov ds ,dx ° 
mov dx,offset myfcb 


; record size = 1 byte 
mov word ptr myfcb+0eh,1 


int 21h ; transfer to MS-DOS 
or al,al ; check status 
jnz error ; jump if no file 


; get file size in bytes 
mov ax,word ptr myfcb+21h 
mov dx,word ptr myfcb+23h 


Sane 
Int 21H [1.0] 


Function 24H (36) 
Set relative record number 


Sets the relative-record-number field of a file control block (FCB) to correspond to the current file 
position as recorded in the opened FCB. 


Call with: AH = 24H 


DS:DX = segment:offset of previously opened file control block 


Returns: AL is destroyed (other registers not affected) 
FCB relative-record field (offset 21H) updated 


Notes: = This function is used when switching from sequential to random I/O within a file. 
The contents of the relative-record field (offset 21H) are derived from the record size 
(offset OEH), current block (offset OCH), and current record (offset 20H) fields of the 
file control block. 


376 = Section I 


= All four bytes of the FCB relative-record field (offset 21H) should be initialized to 
zero before calling this function. 


ae 


Example: After a series of sequential record transfers have been performed using the file control 


block myfcb, obtain the current relative-record position in the file and leave the record 
number in DX. 


myfcb db 0 ; drive = default 
db *MYFILE ‘° ; filename, 8 chars 
db "DAT ’ ; extension, 3 chars 
db 25 dup (0) ; remainder of FCB 
mov dx,seg myfcb ; make FCB addressable 
mov ds ,dx 
: initialize relative 
: record field to zero 
mov word ptr myfcbt+21h,0 
mov word ptr myfcbt+23h,0 
> now set record number 
mov ah, 24h : function number 
mov dx,offset myfcb ; address of FCB 
int 21h ; transfer to MS-DOS 
> load record number in DX 
mov dx,word ptr myfcb+21h 


Int 21H [1.0] 
Function 25H (37) 
Set interrupt vector 


Initializes a CPU interrupt vector to point to an interrupt handling routine. 


Call with: AH = 25H 
AL = interrupt number 
DS:DX = segment:offset of interrupt handling routine 


Returns: Nothing 
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rrr eee 


Notes: = This function should be used in preference to direct editing of the interrupt-vector 
table by well-behaved applications. 


® Before an interrupt vector is modified, its original value should be obtained with 


Int 21H Function 35H and saved, so that it can be restored using this function before 
program termination. 


i ey 
Example: _ install a new interrupt handler, named zdiv, for “divide by zero” CPU exceptions. 


mov ah, 25h ; function number 

mov al,0 ; interrupt number 

mov dx,seg zdiv © ; address of handler 

mov ds ,dx 

mov dx,offset zdiv 

int 2ih ; transfer to MS-DOS 
zdiv: ; int 00h handler 

iret ; (does nothing) 


ee eee eee 
Int 21H [1.0] 


Function 26H (38) 


Create new PSP 
ee 


Copies the program segment prefix (PSP) of the currently executing program to a specified segment 
address in free memory, then updates the new PSP to make it usable by another program. 


Call with: AH = 26H 


DX = segment of new program segment prefix 


Returns: Nothing 


Notes: w After the executing program’s PSP is copied into the new segment, the memory size 
information in the new PSP is updated appropriately and the current contents of the 
termination (Int 22H), Ctrl-C handler (Int 23H), and critical-error handler (Int 24H) 
vectors are saved starting at offset OAH. 

@ This function does not load another program or in itself cause one to be executed. 

@ = [2.0+] Int 21H Function 4BH (EXEC), which can be used to load and execute pro- 
grams or overlays in either .COM or .EXE format, should be used in preference to 
this function. 


378 = Section II 


Example: Create a new program segment prefix 64 KB above the currently executing program. 
This example assumes that the running program was loaded as a .COM file so that the 
CS register points to its PSP throughout its execution. If the running program was loaded 
as a EXE file, the address of the PSP must be obtained with Int 21H Function 62H (under 
MS-DOS 3.0 or later) or by saving the original contents of the DS or ES registers at entry. 


mov ah,26h ; function number 
mov dx,cs > PSP segment of 

; this program 
add dx,1000h ; add 64 KB as 

; paragraph address 
int 2ih ; transfer to MS-DOS 


a 


Int 21H [1.0] 
Function 27H (39) 
Random block read 


a 


Reads one or more sequential records from a file into memory, starting at a designated file location. 


Call with: AH = 27H 
CX = number of records to read 
DS:DX = segment:offset of previously opened file control block 
Returns: AL = 00H if all requested records read 
01H if end of file 
02H if segment wrap 
03H if partial record read at end of file 
CX = actual number of records read 
I 
Notes: m The records are read into memory at the current disk transfer area address, specified 


by the most recent call to Int 21H Function 1AH. It is the programmer's respon- 
sibility to ensure that this area is large enough for the group of records that will be 
transferred. If the size and location of the buffer are such that a segment overflow or 
wraparound would occur, the function fails with a return code of 02H. 


= The file location of the data to be read is determined by the combination of the 
relative-record field (offset 21H) and the record-size field (offset OEH) of the FCB. 
The default record size is 128 bytes. 
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m After the disk transfer is performed, the current block (offset OCH), current record 
(offset 20H), and relative-record (offset 21H) fields of the FCB are updated to point 
to the next record in the file. 


= Ifa partial record is read at the end of file, the remainder of the record is padded 
with zeros. 

= Compare with Int 21H Function 21H, which transfers only one record per function 
call and does not update the FCB relative-record field. 


= [3.0+] If the program is running on a network, the user must have Read access rights 
to the directory containing the file to be read. 


eee 
Example: Read four 1024-byte records starting at record number 8 into the buffer named buff, 


using the file control block myjfcb. 


myfcb db 0 ; drive = default 
db "MYFILE ' ; filename, 8 chars 
db "DAT’ ; extension, 3 chars 
db 25 dup (0) ; remainder of FCB 
buff db 4096 dup (2) ; buffer for data 


; set DTA address 


mov ah,lah ; function number 
mov dx,seg buff ; address of buffer 
mov ds,dx 

mov dx,offset buff 

int 21h ; transfer to MS-DOS 


; set relative-record number 
mov word ptr myfcb+21h,8 
mov word ptr myfcb+23h,0 


; set record size 
mov word ptr myfcbt+0eh, 1024 


; read the records 


mov ah,27h ; function number 
mov cx,4 ; number of records 
mov dx,offset myfcb ; address of FCB 

int 21h ; transfer to MS-DOS 
or al,al ; check status 

jnz error ; jump if read error 


Section IT 


Int 21H [1.0] 
Function 28H (40) 
Random block write 


a al 


Writes one or more sequential records from memory to a file, starting at a designated file location. 


Call with: AH = 28H 
CX = number of records to write 
DS:DX = segment:offset of previously opened file control block 
Returns: AL = 00H if all requested records written 
01H if disk full 
02H if segment wrap 
CX = actual number of records written 


a ee ee oe 

Notes: m The records are written (logically, not necessarily physically) to disk from memory at 
the current disk transfer area address, specified by the most recent call to Int 21H 
Function 1AH. If the size and location of the buffer are such that a segment overflow 
or wraparound would occur, the function fails with a return code of 02H. 


m The file location of the data to be written is determined by the combination of the 


relative-record field (offset 21H) and the record-size field (offset OEH) of the FCB. 
The default record size is 128 bytes. 


= After the disk transfer is performed, the current block (offset OCH), current record 
(offset 20H), and relative-record (offset 21H) fields of the FCB are updated to point 
to the next record in the file. 


= If this function is called with CX = 0, no data is written to the disk but the file is ex- 
tended or truncated to the length specified by combination of the record-size (offset 
OEH) and the relative-record (offset 21H) fields of the FCB. 


= Compare with Int 21H Function 22H, which transfers only one record per function 
call and does not update the FCB relative-record field. 


= (3.0+] If the program is running on a network, the user must have Write access rights 
to the directory containing the file to be written. 


a 
Example: Write four 1024-byte records, starting at record number 8, to disk from the buffer named 
buff, using the file control block my/fcb. 


myfcb db 0 ; drive = default 
db "MYFILE ° ; filename, 8 chars 
db *DAT* ; extension, 3 chars 
db 25 dup (0) ; remainder of FCB 


(continued) 
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buff db 4096 dup (7?) ; buffer for data 


; set DTA address 


mov ah,lah ; function number 
mov dx,seg buff ; address of buffer 
mov ds ,dx 

mov dx,offset buff 

int 2ih ; transfer to MS-DOS 


; set relative-record number 
mov word ptr myfcb+21h,8 
mov word ptr myfcb+23h,0 


; set record size 
mov word ptr myfcb+0eh, 1024 


write the records 


mov ah,28h ; function number 
mov cx,4 ; number of records 
mov dx,offset myfcb ; address of FCB 

int 21h ; transfer to MS-DOS 
or al,al ; check status 


jnz error jump if write error 


eS 
Int 21H [1.0] 


Function 29H (41) 


Parse filename 
SS SSS SSS SS 


Parses a text string into the various fields of a file control block (FCB). 


Callwith: AH = 29H 
AL = flags to control parsing 
Bit3 =1  ifextension field in FCB will be modified only if an 
extension is specified in the string being parsed. 
=O ifextension field in FCB will be modified regardless, if no 
extension is present in the parsed string, FCB extension is 
set to ASCII blanks. 
Bit2 =1 if filename field in FCB will be modified only if a filename is 
Specified in the string being parsed. 
=O if filename field in FCB will be modified regardless, if no 
filename is present in the parsed string, FCB filename is set 
to ASCII blanks. 


382 ~=s Section I 


Bit1 =1 if drive ID byte in FCB will be modified only if a drive was 
specified in the string being parsed. 
=0 if the drive ID byte in FCB will be modified regardless; if no 
drive specifier is present in the parsed string, FCB drive- 
code field is set to O (default). 
BitO =1 if leading separators will be scanned off (ignored). 
=0 if leading separators will not be scanned off. 


DS:SI = segment:offset of string 

ES:DI = segment:offset of file control block 
NN $$ 
Returns: AL = QOH if no wildcard characters encountered 


01H if parsed string contained wildcard characters 
FFH if drive specifier invalid 


DS:SI = segment:offset of first character after parsed filename 
ES:DI = segment:offset of formatted unopened file control block 
I 
Notes: = This function regards the following as separator characters: 
(1) :.3,=+ tab space/"[] 
[20+]  :.;,=+tabspace 
= This function regards all control characters and the following as terminator 
characters: 


_;, = + tab space < >| /"{(] 

= If no valid filename is present in the string to be parsed, upon return ES:DI + 1 
points to an ASCII blank. 

@ Ifthe *« wildcard character occurs in a filename or extension, it and all remaining 
characters in the corresponding field in the FCB are set to ?. 

= This function (and file control blocks in general) cannot be used with file specifica- 
tions that include a path. 


nl a a a SS SS SS SS 


Example: Parse the string fzame into the file control block myjcb. 


fname db "D:QUACK.DAT',O ; filename to be parsed 
myfcb db 37 dup (0) ; becomes file control block 
mov ah,29h : function number 
mov al,QOlh ; skip leading separators 
mov si,seg fname - address of filename 
mov ds,si 
mov si,offset fname 
mov di,seg myfcb > address of FCB 


(continued) 
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mov es ,di 


mov di,offset myfcb 

int 21h ; transfer to MS-DOS 
cmp al ,Offh ; check status 

je error ; jump, drive invalid 


———————— 
Int 21H [1.0] 


Function 2AH (42) 
Get date 


Obtains the system day of the month, day of the week, month, and year. 


a 
Call with: AH = 2AH 


Returns: CX = year (1980 through 2099) 
DH = month (1 through 12) 
DL = day (1 through 31) 
Under MS-DOS versions 1.1 and later 
AL = day of the week (0 = Sunday, 1 = Monday, etc.) 


Notes: = This function’s register format is the same as that required for Int 21H Function 2BH 
(Set Date). 


= This function can be used together with Int 21H Function 2BH to find the day of the 
week for an arbitrary date. The current date is first obtained with Function 2AH and 
saved. The date of interest is then set with Function 2BH, and the day of the week 
for that date is obtained with a subsequent call to Function 2AH. Finally, the current 
date is restored with an additional call to Function 2BH, using the values obtained 
with the original Function 2AH call. 


Example: Obtain the current date and save its components in the variables year, day, and month. 


year dw 0 
month db 0 
day db 0 


384 = Section II 


mov ah, 2ah > function number 


int 21h ; transfer to MS-DOS 
mov year ,cx s save year (word) 
mov month,dh ; save month (byte) 
mov day,dl > save day (byte) 


Int 21H [1.0] 
Function 2BH (43) 
Set date 


Initializes the system clock driver to a specific date. The system time is not affected. 


Call with: AH = 2BH 

CX = year (1980 through 2099) 

DH = month (1 through 12) 

DL = day (1 through 31) 
Returns: AL = 00H if date set successfully 

FFH if date not valid (ignored) 
Note: = This function’s register format is the same as that required for Int 21H Function 2AH 
(Get Date). 


a 


Example: Set the system date according to the contents of the variables year, day, and month. 


year dw 0 
month db 0 
day db 0 
mov ah, 2bh ; function number 
mov cx,year ; get year (word) 
mov dh,month ; get month (byte) 
mov dl ,day ; get day (byte) 
int 21h ; transfer to MS-DOS 
or al,al ; check status 
jnz error ; jump if date invalid 
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STEERER 
Int 21H | [1.0] 


Function 2CH (44) 
Get time 


Obtains the time of day from the system real-time clock driver, converted to hours, minutes, seconds, and 
hundredths of seconds. 


* 


Call with: AH = 2CH 
Returns: CH = hours (0 through 23) 

CL = minutes (0 through 59) 

DH = seconds (0 through 59) 

DL = hundredths of seconds (0 through 99) 
eee 
Notes: = This function’s register format is the same as that required for Int 21H Function 2DH 

(Set Time). 


= On most IBM PC—compatible systems, the real-time clock does not have a resolution 
of single hundredths of seconds. On such machines, the values returned by this 
function in register DL are discontinuous. 


Example: Obtain the current time and save its two major components in the variables hours and 


minutes. 
hours db 0 
minutes db 0 


mov ah,2ch ; function number 

int 21h ; transfer to MS-DOS 
mov hours,ch ; Save hours (byte) 
mov minutes,cl ; Save minutes (byte) 


ee 
Int 21H [1.0] 
Function 2DH (45) 

Set time 
ee ee ee ee ee 


Initializes the system real-time clock to a specified hour, minute, second, and hundredth of second. The 
system date is not affected. 


386 ss Section II 


Call with: AH = 2DH 


CH = hours (0 through 23) 
CL = minutes (0 through 59) 
DH = seconds (0 through 59) 
DL = hundredths of seconds (0 through 99) 
Returns: AL = 00H if time set successfully 
FFH if time not valid Ggnored) 
Note: m This function’s register format is the same as that required for Int 21H Function 2CH 
(Get Time). 


nw 


Example: _ Set the system time according to the contents of the variables hours and minutes. Force 
the current seconds and hundredths of seconds to zero. 


hours db 0 
minutes db 0 
mov ah,2dh : function number 
mov ch,hours ; get hours (byte) 
mov cl,minutes ; get minutes (byte) 
mov dx,0 ; force seconds and 
; hundredths to zero 
int 21h ; transfer to MS-DOS 
or al,al ; check status 
jnz error ; jump if time invalid 


Int 21H [1.0] 
Function 2EH (46) 


Set verify flag 


Turns off or turns on the operating-system flag for automatic read-after-write verification of data. 


Call with: AH = 2EH 
AL = 00H if turning off verify flag 
01H if turning on verify flag 
DL = 00H (MS-DOS versions 1 and 2) 


Returns: Nothing 
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———->>eowc eee 


Notes: = Because read-after-write verification slows disk operations, the default setting of the 
verify flag is OFF. 


= Ifa particular disk unit’s device driver does not support read-after-write verification, 
this function has no effect. 
The current state of the verify flag can be determined using Int 21H Function 54H. 


= The state of the verify flag is also controlled by the MS-DOS commands VERIFY 
OFF and VERIFY ON. 


a es 
Example: Save the current state of the system verify flag in the variable uflag, then force all subse- 
quent disk writes to be verified. 


vflag db 0 ; previous verify flag 


; get verify flag 


mov ah, 54h ; function number 

int 21h ; transfer to MS-DOS 

mov vflag,al >; Save current flag state 
; set verify flag 

mov ah, 2eh ; function number 

mov al,l ; AL = 1 for verify on 

mov d1,0 ; DL must be zero 

int 2ih ; transfer to MS-DOS 


—— 
Int 21H [2.0] 


Function 2FH (47) 


Get DTA address 
ee ee 


Obtains the current address of the disk transfer area (DTA) for FCB file read/write operations. 
eee 
Call with: AH = 2FH 


Returns: ES:BX = segment:offset of disk transfer area 


Note: = The disk transfer area address is set with Int 21H Function 1AH. The default DTA is 
a 128-byte buffer at offset 80H in the program segment prefix. 


388 = Section II 


Example: = Obtain the current disk transfer area address and save it in the variable olddta. 


olddta dd ? ; save disk transfer address 


mov ah,2fh ; function number 
int 2th ; transfer to MS-DOS 


; save it as DWORD pointer 
mov word ptr olddta,bx 
mov word ptr olddtat+2,es 


Int 21H [2.0] 
Function 30H (48) 
Get MS-DOS version number 


Returns the version number of the host MS-DOS operating system. This function is used by application 
programs to determine the capabilities of their environment. 


Call with: AH = 30H 
AL = 0OH 


Returns: If running under MS-DOS version 1 


AL = 00H 

If running under MS-DOS versions 2.0 or later 

AL = major version number (MS-DOS 3.10 = 3, etc.) 

AH = minor version number (MS-DOS 3.10 = OAH, etc.) 

BH = Original Equipment Manufacturer’s (OEM’s) serial number (OEM- 
dependent—usually 00H for IBM’s PC-DOS, OFFH or other values 
for MS-DOS) 

BL:CX = 24-bit user serial number (optional, OEM-dependent) 

Notes: - gs Because this function was not defined under MS-DOS version 1, it should always be 
called with AL = OOH. In an MS-DOS version 1 environment, AL will be returned 
unchanged. 


m= Care must be taken not to exit in an unacceptable fashion if an MS-DOS version 1 en- 
vironment is detected. For example, Int 21H Function 4CH (Terminate Process with 
Return Code), Int 21H Function 40H (Write to File or Device), and the standard error 
handle are not available in MS-DOS version 1. In such cases a program should dis- 


play an error message using Int 21H Function 09H and then terminate with Int 20H 
or Int 21H Function 00H. 
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ns a i es 
Example: Get the MS-DOS version number, terminating the current process with an error message 
if not running under MS-DOS version 2.0 or later. 


cr equ Odh ; ASCII carriage return 
lf equ Oah ; ASCII line feed 
msg db cr,|f 
db "Wrong MS-DOS version’ 
db cr,1f,°$' 
mov ax,3000h ; function number 
int 21h ; transfer to MS-DOS 
cmp al,2 ; version 2 or later? 


jae labell yes, jump 


display error message 


mov ah,09 ; function number 
mov dx,offset msg ; Message address 
int 21h ; transfer to MS-DOS 


; terminate process 


mov ah,0 ; function number 
int 21h ; transfer to MS-DOS 
labell: . 


—————— 
Int 21H [2.0] 


Function 31H (49) 


Terminate and stay resident 
a cea a 


Terminates execution of the currently executing program, passing a return code to the parent process, 
but reserves part or all of the program’s memory so that it will not be overlaid by the next transient pro- 
gram to be loaded. MS-DOS then takes the following actions: 


= File buffers are flushed and any open handles for files or devices owned by the 
process are closed. 


= The termination handler vector (Int 22H) is restored from PSP:000AH. 

m= The Ctrl-C handler vector (Int 23H) is restored from PSP:000EH. 

= [2.0+] The critical-error handler vector (Int 24H) is restored from PSP:0012H. 
# Control is transferred to the termination handler. 


If the program is returning to COMMAND.COM, control transfers to the resident portion, and the tran- 
sient portion is reloaded if necessary. If a batch file is in progress, the next line of the file is fetched and 
interpreted; otherwise, a prompt is issued for the next user command. 


390 ss Section I 


Call with: AH = 31H 


AL = return code 
DX = amount of memory to reserve (in paragraphs) 


Returns: Nothing 


Notes: m This function call is typically used to allow user-written utilities, drivers, or interrupt 
handlers to be loaded as ordinary .COM or .EXE programs and then remain resident. 
Subsequent entrance to the code is via a hardware or software interrupt. 


= This function attempts to set the initial memory allocation block to the length in 
paragraphs specified in register DX. If other memory blocks have been requested 
by the application using Int 21H Function 48H, they will not be released by this 
function. 

= Other methods of performing a final exit are: 


— Int 20H 
— Int 21H Function 00H 
— Int 21H Function 4CH 
— Int 27H 


w The return code may be retrieved by a parent process with Int 21H Function 4DH 
(Get Return Code). It can also be tested in a batch file with an IF ERRORLEVEL 
statement. By convention, a return code of zero indicates successful execution, and a 
nonzero return code indicates an error. 


= This function should not be called by EXE programs that are loaded at the high end 
of the transient program area (that is, linked with the /HIGH switch) because 
doing so reserves the memory that is normally used by the transient part of 
COMMAND.COM. If COMMAND.COM cannot be reloaded, the system will fail. 

w (2.0+] This function should be used in preference to Int 27H because it supports 
return codes, allows larger amounts of memory to be reserved, and does not require 
CS to contain the segment of the program segment prefix. 


= ([3.0+] If the program is running on a network, it should remove all locks it has 
placed on file regions before terminating. 


Example: Exit with a return code of 1 but stay resident, reserving 16 KB of memory starting at the 
program segment prefix of the process. 


mov ah,3ih ; function number 

mov al,l ; return code for parent 
mov dx,0400h ; paragraphs to reserve 
int 21h ; transfer to MS-DOS 
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Int 21H 
Function 32H (50) 
Reserved 


Int 21H [2.0] 
Function 33H (51) 
Get or set break flag, get boot drive 


Obtains or changes the status of the operating system’s break flag, which influences Ctrl-C checking 
during function calls. Also returns the system boot drive in version 4.0. 


Call with: _ If getting break flag 


AH = 33H 

AL = 00H 

If setting break flag 

AH = 33H 

AL = 01H 

DL = 00H if turning break flag OFF 
01H if turning break flag ON 

[4] If getting boot drive 

AH = 33H 

AL = 05H 


Returns: If called with AL = OOH or 01H 


DL = 00H break flag is OFF 
01H break flag is ON 

[4] If called with AL = 05H 

DL = boot drive (1 = A, 2 = B, etc.) 


Notes: m= When the system break flag is on, the keyboard is examined for a Ctrl-C entry 
whenever any operating-system input or output is requested; if Ctrl-C is detected, 
control is transferred to the Ctrl-C handler (Int 23H). When the break flag is off, 
MS-DOS only checks for a Ctrl-C entry when executing the traditional character 
I/O functions (Int 21H Functions 01H through OCH). 

= The break flag is not part of the local environment of the currently executing pro- 
gram; it affects all programs. An application that alters the flag should first save the 
flag’s original status, then restore the flag before terminating. 
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Example: Save the current state of the system break flag in the variable brk/flag, then turn the 
break flag off to disable Ctrl-C checking during most MS-DOS function calls. 


brkflag db 0 : save break flag 


; get current break flag 


mov ah,33h ; function number 

mov al,0 ; AL = 0 to get flag 
int 21h ; transfer to MS-DOS 
mov brkflag,dl ; save current flag 


; now set break flag 


mov ah,33h function number 


mov al,l : AL = 1 to set flag 
mov d1,0 > set break flag OFF 
int 21h - transfer to MS-DOS 


Int 21H 
Function 34H (52) 


Function 35H (53) 
Get interrupt vector 


Obtains the address of the current interrupt-handler routine for the specified machine interrupt. 


Call with: AH = 35H 
AL = interrupt number 
Returns: ES:BX = segment:offset of interrupt handler 
Note: w Together with Int 21H Function 25H (Set Interrupt Vector), this function is used by 
well-behaved application programs to modify or inspect the machine interrupt 
vector table. 
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Example: Obtain the address of the current interrupt handler for hardware interrupt level 0 (divide 
by zero) and save it in the variable oldinto. 


oldintO dd ? ; previous handler address 
mov ah, 35h ; function number 
mov al,0 ; interrupt level 
int 21h ; transfer to MS-DOS 


; save old handler address 
mov word ptr oldint0,bx 
mov word ptr oldint0+2,es 


Int 21H [2.0] 
Function 36H (54) 
Get drive allocation information 


Obtains selected information about a disk drive, from which the drive’s capacity and remaining free 
space can be calculated. 


Call with: AH = 36H 
DL = drive code (0 = default, 1 = A, etc.) 
Returns: If function successful 
AX = sectors per cluster 
BX = number of available clusters 
CX = bytes per sector 
DX = clusters per drive 
If function unsuccessful (drive invalid) 
AX = FFFFH 
Notes: = This function regards “lost” clusters as being in use and does not report them as part 


of the number of available clusters, even though they are not assigned to a file. 
® Similar information is returned by Int 21H Functions 1BH and 1CH. 


Example: Calculate the capacity of disk drive C in bytes, leaving the result in the variable drusize. 
(This code assumes that the product of sectors/cluster + bytes/sector will not overflow 
16 bits.) 


394 = Section II 


drvsize dd ? ; drive C size in bytes 


mov ah,36h ; function number 
mov d1,3 ; drive C = 3 
int 21h ; transfer to MS-DOS 
mul Cx ; sectors/cluster 

; * bytes/sector 
mul dx ; * total clusters 


; result now in DX:AX 


> store low word 


mov word ptr drvsize,ax 
; store high word 
mov word ptr drvsizet+2,dx 


Int 21H 
Function 37H (55) 
Reserved 


Int 21H [2.0] 
Function 38H (56) 
Get or set country information 


[2] Obtains internationalization information for the current country. 


[3.0+] Obtains internationalization information for the current or specified country or sets the current 
country code. 


Call with: _ If getting country information (MS-DOS version 2) 


AH = 38H 

AL =0 to get “current” country information 

DS:DX = segment:offset of buffer for returned information 

If getting country information (MS-DOS versions 3.0 and later) 

AH = 38H 

AL =0 to get “current” country information 
1-FEH to get information for countries with code < 255 
FFH to get information for countries with code >= 255 
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BX = country code, if AL = FFH 


DS:DX = segment:offset of buffer for returned information 
If setting current country code (MS-DOS versions 3.0 and later) 
AH = 38H 
AL = 1-FEH country code for countries with code < 255 
FFH for countries with code >= 255 
BX = country code, if AL = OFFH 
DX = FFFFH 
Returns: If function successful 


Carry flag =clear 


and, if getting internationalization information 

BX = country code 

DS:DX = segment:offset of buffer holding internationalization information 
and buffer filled in as follows: 


(for PC-DOS 2.0 and 2.1) 
Byte(s) Contents 
OOH-01H = date format 
0O=USA mdy 
1=Europe dmy 
2=Japan ymd 
02H-03H  ASCIIZ currency symbol 
04H-O5H  ASCIIZ thousands separator 
06H-07H ASCIIZ decimal separator 
O8H-1FH reserved 


(for MS-DOS versions 2.0 and later, PC-DOS versions 3.0 and later) 
Byte(s) Contents 
OOH-01H date format 

0= USA mdy 

1=Europe dmy 

2=Japan ymd 
02H-06H  ASCIIZ currency symbol string 
07H-08H ASCIIZ thousands separator character 
O9H-OAH ASCIIZ decimal separator character 
OBH-OCH ASCIIZ date separator character 
ODH-OEH ASCIIZ time separator character 


OFH currency format 
bit O =0 if currency symbol precedes value 
=1 if currency symbol follows value 
bit 1 =0 if no space between value and currency symbol 
=1 if one space between value and currency symbol 
bit 2 =0 if currency symbol and decimal are separate 
=1 if currency symbol replaces decimal separator 
10H number of digits after decimal in currency 
11H time format 
bit O =0 if 12-hour clock 


=1 if 24-hour clock 
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Notes: 


Examples: 


12H-15H _ case-map call address 
16H-17H  ASCIIZ data-list separator 
18H-21H reserved 


If function unsuccessful 
Carry flag =set 
AX = error code 


™ The default country code is determined by the COUNTRY= directive in 
CONFIG.SYS or by the KEYBxx keyboard driver file if one is loaded. Otherwise, 
the default country code is OEM-dependent. 


® The previous contents of register CX may be destroyed by the Get Country Informa- 
tion subfunction. 


= The case-map call address is the segment:offset of a FAR procedure that performs 
country-specific mapping on character values from 80H through OFFH. The pro- 
cedure must be called with the character to be mapped in register AL. If an alternate 
value exists for that character, it is returned in AL; otherwise, AL is unchanged. In 
general, lowercase characters are mapped to their uppercase equivalents, and ac- 
cented or otherwise modified vowels are mapped to their plain vowel equivalents. 


@ [3.0+] The value in register DX is used by MS-DOS to select between the Set Country 
and Get Country Information subfunctions. 


@ (3.3+] Int 21H Function 65H (Get Extended Country Information) returns a superset 
of the information supplied by this function. 


Obtain internationalization information for the current country in the buffer ctrybuf. 


ctrybuf db 34 dup (0) 


mov ah, 38h ; function number 

mov al,0 ; get current country 

mov dx,seg ctrybuf ; address of buffer 

mov ds ,dx ; for country information 
mov dx,offset ctrybuf 

int 2ih ; transfer to MS-DOS 

jc error ; jump if function failed 


If the program is running under PC-DOS 3.3 and the current country code is 49 (West 
Germany), ctrybuf is filled in with the following information: 


dw 0001h ; date format 
db "DM" ,0,0,0 ; ASCIIZ currency symbol 
db ara ; ASCIIZ thousands separator 
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db grees t| ; ASCIIZ decimal separator 
db anaes! ; ASCIIZ date separator 
db eke: 0 ; ASCIIZ time separator 
db 02h ; currency format 
db 02h ; digits after decimal 
db Olh ; time format 
dd 026ah:176ch ; case-map call address 
db ta 0 ; ASCIIZ data-list separator 
db 10 dup (0) ; reserved 
Int 21H [2.0] 
Function 39H (57) 
Create directory 
Creates a directory using the specified drive and path. 
Call with: AH = 39H 
DS:DX = segment:offset of ASCIIZ pathname 
Returns: If function successful 
Carry flag =clear 
If function unsuccessful 
Carry flag =set 
AX = error code 
Note: ®@ The function fails if: 
~— any element of the pathname does not exist. 
— adirectory with the same name at the end of the same path already exists. 
— the parent directory for the new directory is the root directory and is full. 
— [3.0+] the program is running on a network and the user running the program has 
insufficient access rights. 
Example: Create a directory named MYSUB in the root directory on drive C. 


dname db *C:\MYSUB' ,0 
mov ah, 39h ; function number 
mov dx,seg dname ; address of pathname 
mov ds,dx 
mov dx,offset dname 
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int 21h ; transfer to MS-DOS 
jc error ; jump if create failed 


Int 21H [2.0] 
Function 3AH (58) 
Delete directory 


Removes a directory using the specified drive and path. 


Call with: AH = 3AH 
DS:DX = segment:offset of ASCIIZ pathname 


Returns: If function successful 
Carry flag =clear 


If function unsuccessful 
Carry flag =set 
AX = error code 


Note: @ The function fails if: 


— any element of the pathname does not exist. 

— the specified directory is also the current directory. 

the specified directory contains any files. 

[3.0+] the program is running on a network and the user running the program has 
insufficient access rights. 


Example: Remove the directory named MYSUB in the root directory on drive C. 


dname db *C:\MYSUB’ ,0 
mov ah,3ah ; function number 
mov dx,seg dname ; address of pathname 
mov ds ,dx 
mov dx,offset dname 
int 21h ; transfer to MS-DOS 
jc error ; jump if delete failed 
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Int 21H [2.0] 
Function 3BH (59) 
Set current directory 


Sets the current, or default, directory using the specified drive and path. 


Call with: AH = 3BH 
DS:DX = segment:offset of ASCIIZ pathname 


Returns: If function successful 
Carry flag =clear 
If function unsuccessful 
Carry flag =set 
AX = error code 


Notes: = The function fails if any element of the pathname does not exist. 
@ [nt 21H Function 47H can be used to obtain the name of the current directory before 
using Int 21H Function 3BH to select another, so that the original directory can be 
restored later. 


Example: Change the current directory for drive C to the directory \MYSUB. 


dname db "C:\MYSUB" ,0 
mov ah,3bh ; function number 
mov dx,seg dname ; address of pathname 
mov ds,dx 
mov dx,offset dname 
int 21h ; transfer to MS-DOS 
jc error ; jump if bad path 
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Int 21H 


7h at 


[2.0] 


Function 3CH (60) 
Create file 


Given an ASCIIZ pathname, creates a new file in the designated or default directory on the designated or 
default disk drive. If the specified file already exists, it is truncated to zero length. In either case, the file is 
opened and a handle is returned that can be used by the program for subsequent access to the file. 


Call with: 


Returns: 


Notes: 


AH = 3CH 
CX = file attribute (bits may be combined) 
Bit(s) Significance (if set) 
0 read-only 
1 hidden 
2 system 
3 volume label 
4 reserved (0) 
5 archive 
6-15 reserved (0) 
DS:DX = segment:offset of ASCIIZ pathname 
If function successful 
Carry flag =clear 
AX = handle 
If function failed 
Carry flag =set 
AX = error code 


@ The function fails if: 


— any element of the pathname does not exist. 

— the file is being created in the root directory and the root directory is full. 

— a file with the same name and the read-only attribute already exists in the speci- 
fied directory. 

— [3.0+] the program is running on a network and the user running the program has 
insufficient access rights. 

= A file is usually given a normal (0) attribute when it is created. The file’s attribute 
can subsequently be modified with Int 21H Function 43H. 


= [3.0+] A volume label can be created using an attribute of 0008H, if one does not 
already exist. When files are created, bit 3 of the attribute parameter should always 
be clear (0). 


= [3.0+] See the entries for Int 21H Functions 5AH and 5BH, which may also be used to 
create files. 


@ (4.0+] Int 21H Function 6CH combines the services of Functions 3CH, 3DH, 
and 5BH. 
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Example: Create and open, or truncate to zero length and open, the file C:\MYDIR\MYFILE.DAT, 
and save the handle for subsequent access to the file. 


fname db *C:\MYDIR\MYFILE.DAT' ,0 
fhandle dw ? 
mov ah,3ch ; function number 
xor CX,CX ; normal attribute 
mov dx,seg fname ; address of pathname 
mov ds,dx 
mov dx,offset fname 
int 21h ; transfer to MS-DOS 
jc error ; jump if create failed 
mov fhandle,ax ; save file handle 


Int 21H [2.0] 
Function 3DH (61) 
Open file 


Given an ASCIIZ pathname, opens the specified file in the designated or default directory on the desig- 
nated or default disk drive. A handle is returned which can be used by the program for subsequent access 
to the file. 


Call with: AH = 3DH 
AL = access mode 

Bit(s) Significance 

0-2 access mode 
000 = read access 
001 = write access 
010 = read/write access 

3 reserved (0) 

4-6 sharing mode (MS-DOS versions 3.0 and later) 


000 = compatibility mode 
001 = deny all 
010 = deny write 
011 = deny read 
100 = deny none 
7 inheritance flag (MS-DOS versions 3.0 and later) 
0 = child process inherits handle 
1 = child does not inherit handle 
DS:DX = segment:offset of ASCIIZ pathname 
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Returns: 


If function successful 
Carry flag =clear 

AX = handle 

If function unsuccessful 
Carry flag =set 

AX = error code 


Notes: 


@ Any normal, system, or hidden file with a matching name will be opened by this 
function. If the file is read-only, the success of the operation also depends on the 
access code in bits 0-2 of register AL. After opening the file, the file read/write 

pointer is set to offset zero (the first byte of the file). 

= The function fails if: 


— any element of the pathname does not exist. 

— the file is opened with an access mode of read/write and the file has the read- 
only attribute. 

— [3.0+] SHARE.EXE is loaded and the file has already been opened by one or more 
other processes in a sharing mode that is incompatible with the current program’s 
request. 


m™ The file’s date and time stamp can be accessed after a successful open call with 
Int 21H Function 57H. 

= The file’s attributes (hidden, system, read-only, or archive) can be obtained with 
Int 21H Function 43H. 

™ When a file handle is inherited by a child process or is duplicated with Int 21H 
Function 45H or 46H, all sharing and access restrictions are also inherited. 

= [2] Only bits 0-2 of register AL are significant; the remaining bits should be zero for 
upward compatibility. 

= [3.0+] Bits 4-7 of register AL control access to the file by other programs. (Bits 4—6 
have no effect unless SHARE.EXE is loaded.) 

a [3.0+] A file-sharing error causes a critical-error exception (Int 24H) with an error 
code of 02H. Int 21H Function 59H can be used to obtain information about the 
sharing violation. 

= [4.0+] Int 21H Function 6CH combines the services of Functions 3CH, 3DH, 
and 5BH. 


Example: 


Open the file C:\MYDIR\MYFILE.DAT for both reading and writing, and save the 
handle for subsequent access to the file. 


fname db "C:\MYDIR\MYFILE.DAT’ ,O 


fhandle dw ? 
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mov ah,3dh ; function number 


mov al,2 ; mode = read/write 
mov dx,seg fname ; address of pathname 
mov ds ,dx 

mov dx,offset fname 

int 2ih ; transfer to MS-DOS 
jc error ; jump if open failed 
mov fhandle,ax ; save file handle 


Int 21H [2.0] 
Function 3EH (62) | 
Close file 


Given a handle that was obtained by a previous successful open or create operation, flushes all internal 
buffers associated with the file to disk, closes the file, and releases the handle for reuse. If the file was 
modified, the time and date stamp and file size are updated in the file’s directory entry. 


Call with: AH = 3EH 
BX = handle 
Returns: If function successful 


Carry flag =clear 

If function unsuccessful 
Carry flag = set 

AX = error code 


Note: = If you accidentally call this function with a zero handle, the standard input device is 
closed, and the keyboard appears to go dead. Make sure you always call the close 
function with a valid, nonzero handle. 


Example: Close the file whose handle is saved in the variable fhandle. 


fhandle dw 0 
mov ah, 3eh ; function number 
mov bx, fhandle ; file handle 
int 2ih ; transfer to MS-DOS 
je error ; jump if close failed 
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Int 21H [2.0] 
Function 3FH (63) 
Read file or device 


Given a valid file handle from a previous open or create operation, a buffer address, and a length in bytes, 
transfers data at the current file-pointer position from the file into the buffer and then updates the file 
pointer position. 


Call with: AH = 3FH 
BX = handle 
CX = number of bytes to read 
DS:DX = segment:offset of buffer 
Returns: If function successful 
Carry flag =clear 
AX = bytes transferred 


If function unsuccessful 
Carry flag =set 
AX = error code 


Notes: @ If reading from a character device (such as the standard input) in cooked mode, at 
most one line of input will be read (i.e., up to a carriage return character or the 
specified length, whichever comes first). 


™ Ifthe carry flag is returned clear but AX = 0, then the file pointer was already at end 
of file when the program requested the read. 


@ Ifthe carry flag is returned clear but AX < CX, then a partial record was read at end 
of file or there is an error. 


= ([3.0+] If the program is running on a network, the user must have Read access rights 
to the directory and file. 


Example: Using the file handle from a previous open or create operation, read 1024 bytes at the 


current file pointer into the buffer named bu/f. 


buff db 1024 dup (7?) ; buffer for read 


fhandle dw ? : contains file handle 
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mov ah,3fh ; function number 


mov dx,seg buff ; buffer address 

mov ds,dx 

mov dx,offset buff 

mov bx, fhandle ; file handle 

mov cx,1024 ; length to read 

int 21h ; transfer to MS-DOS 
jc error ; jump, read failed 
cmp ax,cx ; check length of read 
jl done ; jump, end of file 


Int 21H [2.0] 
Function 40H (64) 
Write file or device 


Given a valid file handle from a previous open or create operation, a buffer address, and a length in bytes, 
transfers data from the buffer into the file and then updates the file pointer position. 


Call with: AH = 40H 
BX = handle 
CX = number of bytes to write 
DS:DX = segment:offset of buffer 


Returns: If function successful 
Carry flag =clear 
AX = bytes transferred 
If function unsuccessful 
Carry flag = set 
AX = error code 


Notes: @ If the carry flag is returned clear but AX < CX, then a partial record was written or 
there is an error. This can be caused by a Ctrl-Z (1AH) embedded in the data if the 
destination is a character device in cooked mode or by a disk full condition if the 
destination is a file. 

= If the function is called with CX = 0, the file is truncated or extended to the current 
file pointer position. 

™ [3.0+] If the program is running on a network, the user must have Write access rights 
to the directory and file. 
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Example: Using the handle from a previous open or create operation, write 1024 bytes to disk at 
the current file pointer from the buffer named bu/ff- 


buff db 1024 dup (?) ; buffer for write 
fhandle dw ? ; contains file handle 
mov ah,40h ; function number 
mov dx,seg buff ; buffer address 
mov ds,dx 
mov dx,offset buff 
mov bx, fhandle ; file handle 
mov cx,1024 : length to write 
int 21h ; transfer to MS-DOS 
jc error ; jump, write failed 
cmp ax,1024 ; entire record written? 
jne error ; no, jump 


Int 21H [2.0] 
Function 41H (65) 
Delete file 


Deletes a file from the specified or default disk and directory. 


Call with: AH = 41H 
DS:DX = segment:offset of ASCIIZ pathname 
Returns: If function successful 


Carry flag = clear 

If function unsuccessful 
Carry flag =set 

AX = error code 


Notes: ™ This function deletes a file by replacing the first character of its filename in the 
directory with the character e (E5H) and marking the file’s clusters as “free” in the 
disk’s file allocation table. The actual data stored in those clusters is not overwritten. 


®@ Only one file at a time may be deleted with this function. Unlike the FCB-related 
Delete File function (Int 21H Function 13H), the « and ? wildcard characters are not 
allowed in the file specification. 
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= The function fails if: 


— any element of the pathname does not exist. 

— the designated file exists but has the read-only attribute. (Int 21H Function 43H 
can be used to examine and modify a file’s attribute before attempting to 
delete it.) 

— [3.0+] the program is running on a network, and the user running the program 
has insufficient access rights. 


Example: Delete the file named MYFILE.DAT from the directory \MYDIR on drive C. 


fname db "C:\MYDIR\MYFILE.DAT' ,O 
mov ah,4ih ; function number 
mov dx,seg fname ; filename address 
mov ds,dx 
mov dx,offset fname 
int 21h ; transfer to MS-DOS 
jc error ; jump if delete failed 


Int 21H [2.0] 
Function 42H (66) 
Set file pointer 


Sets the file location pointer relative to the start of file, end of file, or current file position. 


Call with: AH = 42H 
AL = method code 
00H absolute offset from start of file 
01H signed offset from current file pointer 
02H signed offset from end of file 


BX = handle 
CX = most significant half of offset 
Dx = least significant half of offset 


Returns: If function successful 
Carry flag =clear , 
DX = most significant half of resulting file pointer 
AX = least significant half of resulting file pointer 


If function unsuccessful 
Carry flag = set 
AX = error code 
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Notes: = This function uses a method code and a double-precision (32-bit) value to set the file 
pointer. The next record read or written in the file will begin at the new file pointer 
location. No matter what method is used in the call to this function, the file pointer 
returned in DX:AX is always the resulting absolute byte offset from the start of file. 

= Method 02H may be used to find the size of the file by calling Int 21H Function 42H 
with an offset of 0 and examining the pointer location that is returned. 

® Using methods 01H or 02H, it is possible to set the file pointer to a location that is 
before the start of file. If this is done, no error is returned by this function, but an 
error will be encountered upon a subsequent attempt to read or write the file. 


Examples: Using the file handle from a previous open or create operation, set the current file 
pointer position to 1024 bytes after the start of file. 


fhandle dw ? 
mov ah,42h ; function number 
mov al,0 ; method = absolute 
mov bx, fhandle ; file handle 
mov cx,0 ; upper half of offset 
mov dx,1024 ; lower half of offset 
int 2ih ; transfer to MS-DOS 
jc error ; jump, function failed 


The following subroutine accepts a record number, record size, and handle and sets the 
file pointer appropriately. 


; call this routine with BX = handle 

; AX = record number 
; CX = record size 

> returns all registers unchanged 


setptr proc near 
push ax ; save record number 
push CX ; save record size 
push dx ; save whatever's in DX 
mul CX ; size * record number 
mov CX,ax ; upper part to CX 
xchg cx,dx ; lower part to DX 
mov ax,4200h ; function number & method 
int 21h ; transfer to MS-DOS 
pop dx ; restore previous DX 
pop cx ; restore record size 
pop ax ; restore record number 
ret ; back to caller 


setptr endp 
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Int 21H [2.0] 
Function 43H (67) 
Get or set file attributes 


Obtains or alters the attributes of a file (read-only, hidden, system, or archive) or directory. 


Call with: AH = 43H 

AL = 00H to get attributes 
01H to set attributes 

CX = file attribute, if AL = 01H (bits can be combined) 
Bit(s) Significance (if set) 
0 read-only 
1 hidden 
2 system 
3-4 reserved (0) 
5 archive 
6-15 reserved (0) 

DS:DX = segment:offset of ASCIIZ pathname 

Returns: If function successful 

Carry flag =clear 

CX = file attribute 
Bit(s) Significance (if set) 
0 read-only 
1 hidden 
Z system 
3 volume label 
4 directory 
5 archive 
6-15 reserved (0) 


If function unsuccessful 
Carry flag = set 
AX = error code 


Notes: w Bits 3 and 4 of register CX must always be clear (0) when this function is called; in 
other words, you cannot change an existing file into a directory or volume label. 
However, you can assign the “hidden” attribute to an existing directory with this 
function. 
= ([3.0+] If the program is running on a network, the user must have Create access 
rights to the directory containing the file whose attribute is to be modified. 
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Example: — Change the attribute of the file D:\MYDIR\MYFILE.DAT to read-only, so that it cannot 
be accidentally modified or deleted by other application programs. 


rdonly equ Olh ; file attributes 
hidden equ 02h 
system equ 04h 

volume equ 08h 

subdir equ 10h 

archive equ 20h 

fname db 'D: \MYDIR\MYFILE. DAT" ,0 
mov ah,43h ; function number 
mov al,QOlh ; subfunction = modify 
mov cx,rdonly ; read-only attribute 
mov dx,seg fname ; filename address 
mov ds ,dx 
mov dx,offset fname 
int 2ih ; transfer to MS-DOS 
jc error ; jump if modify failed 


Int 21H [2.0] 
Function 44H (68) 
IOCTL (//O control) 


Provides a direct path of communication between an application program and a device driver. Allows a 
program to obtain hardware-dependent information and to request operations that are not supported by 
other MS-DOS function calls. 


The IOCTL subfunctions and the MS-DOS versions in which they first became available are: 


Subfunction Name MS-DOS version 
00H Get Device Information 2.0 
01H Set Device Information 2.0 
02H Receive Control Data from Character Device Driver 2.0 
03H Send Control Data to Character Device Driver 2.0 
04H Receive Control Data from Block Device Driver 2.0 
05H Send Control Data to Block Device Driver 2.0 
06H Check Input Status 2.0 
(continued) 
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continued 


SSS 


Subfunction Name MS-DOS version 


07H Check Output Status 2.0 
08H Check If Block Device Is Removable 3.0 
09H Check If Block Device Is Remote 3.1 
OAH (10) Check If Handle Is Remote 3.1 
OBH (11) Change Sharing Retry Count 3.1 
OCH (12) Generic I/O Control for Character Devices 
CL = 45H: Set Iteration Count 3.2 
CL = 4AH: Select Code Page 3.3 
CL = 4CH: Start Code Page Preparation 3.3 
CL = 4DH: End Code Page Preparation 3.3 
CL = 5FH: Set Display Information 4.0 
CL = 65H: Get Iteration Count 3.2 
CL = 6AH: Query Selected Code Page 3.3 
CL = 6BH: Query Prepare List 3.3 
CL = 7FH: Get Display Information 4.0 
ODH (13) Generic I/O Control for Block Devices 
CL = 40H: Set Device Parameters 3.2 
CL = 41H: Write Track 3.2 
CL = 42H: Format and Verify Track 3.2 
CL = 47H: Set Access Flag 4.0 
CL = 60H: Get Device Parameters | 3.2 
CL = 61H: Read Track 3.2 
CL = 62H: Verify Track 3.2 
CL = 67H: Get Access Flag 4.0 
OEH (14) Get Logical Drive Map 3.2 
OFH (15) Set Logical Drive Map 3.2 


Only IOCTL Subfunctions 00H, 06H, and 07H may be used for handles associated with files. Subfunctions 
OOH-—08H are not supported on network devices. 


a 
Int 21H [2.0] 
Function 44H (68) Subfunction 00H 

IOCTL: get device information 
ee a ee 


Returns a device information word for the file or device associated with the specified handle. 


Call with: AH = 44H 
AL = 0OH 
BX | = handle 
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Returns: If function successful 
Carry flag =clear 


DX = device information word 
For a file: 
Bit(s) Significance 
0-5 drive number (0 = A, 1 = B, etc.) 
6 0 if file has been written 
1 if file has not been written 
r O, indicating a file 
8-15 reserved 
For a device: 
Bit(s) Significance 
0 1 if standard input 
1 1 if standard output 
2 1 if NUL device 
3 1 if clock device 
4 reserved 
5 O if handle in ASCII mode 
1 if handle in binary mode 
6 0 if end of file on input 
7 1, indicating a device 
8-13 reserved 
14 0 if IOCTL subfunctions 02H and 03H not supported 
1 if IOCTL subfunctions 02H and 03H supported 
15 reserved 


If function unsuccessful 
Carry flag =set 


AX = error code 


a 


Notes: ™ Bits 8—15 of DX correspond to the upper 8 bits of the device-driver attribute word. 


@ Bit 5 of the device information word for a handle associated with a character device 
signifies whether MS-DOS considers that handle to be in binary (“raw”) mode or 
ASCII (“cooked”) mode. In ASCII mode, MS-DOS filters the character stream and 
may take special action when the characters Ctrl-C, Ctrl-S, Ctrl-P, Ctrl-Z, and car- 
riage return are detected. In binary mode, all characters are treated as data, and the 
exact number of characters requested is always read or written. 


o_O 


Example: — See Int 21H Function 44H Subfunction 01H. 
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Int 21H [2.0] 
Function 44H (68) Subfunction 01H 
IOCTL: set device information 


Sets certain flags for a handle associated with a character device. This subfunction may not be used for a 
handle that is associated with a file. 


Call with: AH = 44H 
AL = 01H 
BX = handle 
DX = device information word 


Bit(s) Significance 
0 1 if standard input 
1 1 if standard output 
2 1 if NUL device 
3 1 if clock device 
4 reserved (0) 
5 0 to select ASCII mode 
1 to select binary mode 
6 reserved (0) 
7 1, indicating a device 
8-15 reserved (0) 
eee 
Returns: If function successful 
Carry flag =clear 
If function unsuccessful 
Carry flag =set 


AX = error code 
eee 
Notes: = If register DH does not contain 00H, control returns to the program with the carry 


flag set and error code 0001H (invalid function) in register AX. 

= Bit 5 of the information word for a handle associated with a character device sig- 
nifies whether MS-DOS considers that handle to be in binary (“raw”) or ASCII 
(“cooked”) mode. See Notes for Int 21H Function 44H Subfunction 00H. 


eee 
Example: Place the standard output handle into binary (“raw”) mode. This speeds up output by 


disabling checking for Ctrl-C, Ctrl-S, and Ctrl-P between each character. 
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get device information 


mov ax,4400h > function & subfunction 
mov bx,1 ; standard output handle 
int 21h > transfer to MS-DOS 
mov dh,0 ; force DH = 0 
or d1,20h > set binary mode bit 

- set device information 
mov ax,4401h - function & subfunction 
int 21h > transfer to MS-DOS 


A Sans 


Int 21H [2.0] 
Function 44H (68) Subfunction 02H 
IOCTL: read control data from character device driver 


ss. 


Reads control data from a character-device driver. The length and contents of the data are specific to 
each device driver and do not follow any standard format. This function does not necessarily result in any 
input from the physical device. 


Call with: AH = 44H 

AL = 02H 

BX = handle 

CX = number of bytes to read 

DS:DX = segment:offset of buffer 
NN. ——— 
Returns: If function successful 

Carry flag = clear 

AX = bytes read 


~ and buffer contains control data from driver 
If function unsuccessful 
Carry flag =set 
AX = error code 


ee 


Notes: = If supported by the driver, this subfunction can be used to obtain hardware- 
dependent status and availability information that is not supported by other 
MS-DOS function calls. 
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™ Character-device drivers are not required to support IOCTL Subfunction 02H. A pro- 
gram can test bit 14 of the device information word returned by IOCTL Subfunction 
00H to determine whether the driver supports this subfunction. If Subfunction 02H 
is requested and the driver does not have the ability to process control data, control 
returns to the program with the carry flag set and error code 0001H (invalid func- 
tion) in register AX. 


= _ eee 


Example: Read a control string from the standard list driver into the buffer buff. 


stdprn equ 4 ; Standard list handle 
buflen equ 64 ; length of buffer 
ctilen dw ? ; length of control string 
buff db bufien dup (0) ; receives control string 
mov ax,4402h ; function & subfunction 
MOV bx, stdprn ; Standard list handle 
mov cx, buflen ; buffer length 
mov dx,seg buff ; buffer address 
mov ds,dx 
mov dx,offset buff 
int 2ih ; transfer to MS-DOS 
jc error ; jump if read failed 
mov ctllen,ax ; Save control string length 


Sa Ee 
Int 21H [2.0] 


Function 44H (68) Subfunction 03H 


IOCTL: write control data to character-device driver 
a ee ee een eee 


Transfers control data from an application to a character-device driver. The length and contents of the 
data are specific to each device driver and do not follow any standard format. This function does not 
necessarily result in any output to the physical device. 


Call with: AH = 44H 
AL = 03H 
BX = handle 
CX = number of bytes to write 
DS:DX = segment:offset of data 
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Returns: 


If function successful 


Carry flag 
AX 


= clear 
= bytes transferred 


If function unsuccessful 


Carry flag 
AX 


= error code 


Notes: 


= If supported by the driver, this subfunction can be used to request hardware- 


dependent operations (such as setting baud rate for a serial port) that are not sup- 
ported by other MS-DOS function calls. 


™ Character-device drivers are not required to support IOCTL Subfunction 03H. A pro- 
gram can test bit 14 of the device information word returned by IOCTL Subfunction 
OOH to determine whether the driver supports this subfunction. If Subfunction 03H 
is requested and the driver does not have the ability to process control data, control 
returns to the program with the carry flag set and error code 0001H (invalid func- 
tion) in register AX. 


Example: 


Write a control string from the buffer buff to the standard list device driver. The length 
of the string is assumed to be in the variable céllen. 


stdprn equ 
buflen equ 


ctllen dw 
buff db 


mov 
mov 
mov 
mov 
mov 
mov 
int 
jc 


4 
64 


? 
buflen dup (?) 


ax,4403h 
bx,stdprn 
dx,seg buff 

ds ,dx 
dx,offset buff 
cx,ctllen 

2lh 

error 


: standard list handle 


length of buffer 


length of control data 


> contains control data 


> function & subfunction 
- standard list handle 


buffer address 


; length of control data 


transfer to MS-DOS 
jump if write failed 
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Int 21H [2.0] 
Function 44H (68) Subfunction 04H 
IOCTL: read control data from block-device driver 


Transfers control data from a block-device driver directly into an application program’s buffer. The length 
and contents of the data are specific to each device driver and do not follow any standard format. This 
function does not necessarily result in any input from the physical device. 


Call with: AH = 44H 
AL = 04H 
BL = drive code (0 = default, 1 = A, 2 = B, etc.) 
CX = number of bytes to read 
DS:DX = segment:offset of buffer 


a ee a ee ee ee 
Returns: If function successful 


Carry flag =clear 

AX = bytes transferred 

and buffer contains control data from device driver 
If function unsuccessful 

Carry flag = set 


AX = error code 
nh a a 
Notes: ™ When supported by the driver, this subfunction can be used to obtain hardware- 


dependent status and availability information that is not provided by other MS-DOS 
function calls. 


® Block-device drivers are not required to support IOCTL Subfunction 04H. If this 
subfunction is requested and the driver does not have the ability to process control 
data, control returns to the program with the carry flag set and error code 0001H 
Ginvalid function) in register AX. 


a 
Example: Read a control string from the block-device driver for drive C into the buffer buff. 


buflen equ 64 ; length of buffer 
ctllen dw ? ; length of control string 
buff db buflen dup (0) ; receives control] string 
mov ax,4404h ; function & subfunction 
mov b1,3 ; drive C = 3 
mov cx, buflen ; buffer length 
mov dx,seg buff ; buffer address 
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mov ds,dx 


mov dx,offset buff 

int 21h ; transfer to MS-DOS 

jc error ; jump if read failed 

mov ctllen,ax > save control string length 


Int 21H [2.0] 
Function 44H (68) Subfunction 05H 
IOCTL: write control data to block-device driver 


Transfers control data from an application program directly to a block-device driver. The length and con- 
tents of the control data are specific to each device driver and do not follow any standard format. This 
function does not necessarily result in any output to the physical device. 


Call with: AH = 44H 

AL = 05H 

BL = drive code (0 = default, 1 = A, 2 = B, etc.) 

CX = number of bytes to write 

DS:DX = segment:offset of data 
ee ee ee 
Returns: If function successful 

Carry flag =clear 

AX = bytes transferred 


If function unsuccessful 
Carry flag =set 
AX = error code 


re 


Notes: m When supported by the driver, this subfunction can be used to request hardware- 
dependent operations (such as tape rewind or disk eject) that are not provided by 
other MS-DOS function calls. 


= Block-device drivers are not required to support IOCTL Subfunction 05H. If this 
subfunction is requested and the driver does not have the ability to process control 
data, control returns to the program with the carry flag set and error code 0001H 
(invalid function) in register AX. 


a 


Example: Write a control string from the buffer buff to the block-device driver for drive C. The 
length of the string is assumed to be in the variable céllen. 


buflen equ 64 ; length of buffer 


ctllen dw ? ; length of control data 


(continued) 
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buff db buflen dup (?) ; contains control data 


mov ax,4405h 


; function & subfunction 
mov b1,3 ; drive C = 3 
mov dx,seg buff ; buffer address 
mov ds ,dx 
mov dx,offset buff 
mov cx,ctllen ; length of control data 
int 21h ; transfer to MS-DOS 
jc error ; jump if write failed 


SSS SS SSS SS 
Int 21H [2.0] 
Function 44H (68) Subfunction 06H 


IOCTL: check input status 
ee ee 


Returns a code indicating whether the device or file associated with a handle is ready for input. 


Call with: AH = 44H 
AL = 06H 
Bx = handle 


Returns: If function successful 

Carry flag =clear 

and, for a device: 

AL = 00H if device not ready 
FEH if device ready 

or, for a file: 

AL = 00H if file pointer at EOF 
FFH if file pointer not at EOF 

If function unsuccessful 

Carry flag = set 


AX = error code 
Se a ea ee a eee eee 
Note: = This function can be used to check the status of character devices, such as the serial 


port, that do not have their own “traditional” MS-DOS status calls. 
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Example: Check whether a character is ready from the standard auxiliary device (usually COM1). 


Stdaux equ 3 ; standard auxiliary handle 
mov ax,4406h ; function & subfunction 
mov bx,stdaux ; standard auxiliary handle 
int 21h ; transfer to MS-DOS 
jc error ; jump if function failed 
or al,al ; test status flag 
jnz ready ; jump if character ready 


Int 21H [2.0] 
Function 44H (68) Subfunction 07H 
IOCTL: check output status 


Returns a code indicating whether the device associated with a handle is ready for output. 


Call with: AH = 44H 
AL = 07H 
BX = handle 

Returns: If function successful 


Carry flag =clear 


and, for a device: 

AL = 00H if device not ready 
FFH if device ready 

or, for a file: 

AL = FFH 

If function unsuccessful 

Carry flag =set 

AX = error code 


Note: ws When used with a handle for a file, this function always returns a ready status, even 
if the disk is full or no disk is in the drive. 
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Example: Check whether the standard auxiliary device (usually COM) can accept a character 


for output. 

Stdaux equ 3 ; standard auxiliary handle 
mov ax,4407h ; function & subfunction 
mov bx,stdaux ; standard auxiliary handle 
int 21h ; transfer to MS-DOS 
jc error ; jump if function failed 
or al,al ; test status flag 
jnz ready ; jump if not busy 


Int 21H [3.0] 
Function 44H (68) Subfunction 08H 
IOCTL: check if block device is removable 


Checks whether the specified block device contains a removable storage medium, such as a floppy disk. 


Call with: AH = 44H 
AL = 08H 
BL = drive number (0 = default, 1 = A, 2 = B, etc.) 


Returns: If function successful 
Carry flag =clear 
AL = 00H if medium is removable 
01H if medium is not removable 
If function unsuccessful 
Carry flag = set 
AX = error code 


Notes: m Ifa file is not found as expected on a particular drive, a program can use this sub- 
function to determine whether the user should be prompted to insert another disk. 
= This subfunction may not be used for a network drive. 
= Block drivers are not required to support Subfunction 08H. If this subfunction is 
requested and the block device cannot supply the information, control returns to 
the program with the carry flag set and error code 0001H (invalid function) in 
register AX. 
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a 


Example: = Check whether drive C is removable. 


mov ax,4408h ; function & subfunction 
mov b1,3 ; drive 3 =+C 

int 21h ; transfer to MS-DOS 

jc error ; jump if function failed 
and al,l ; test type of medium 

jnz fixed ; jump if not removable 


Int 21H [3.1] 
Function 44H (68) Subfunction 09H 
IOCTL: check if block device is remote 


Checks whether the specified block device is local (attached to the computer running the program) or 
remote (redirected to a network server). 


Call with: AH = 44H 

AL = 09H 

BL = drive number (0 = default, 1 = A, 2 = B, etc.) 
Returns: If function successful 

Carry flag =clear 

DX = device attribute word 


bit12 = Oif drive is local 
1 if drive is remote 
If function unsuccessful 
Carry flag =set 
AX = error code 


Note: m Use of this subfunction should be avoided. Application programs should not distin- 
guish between files on local and remote devices. 
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ye Ee eee 
Example: Check whether drive D is mounted on the machine running the program or is a network 
drive. 


mov ax,4409h function & subfunction 


mov b1,4 ; drive 4=)D 
int 21h ; transfer to MS-DOS 
jc error ; jump if function failed 


and dx,1000h 
jnz remote 


test local/remote bit 
jump if network drive 


Int 21H [3.1] 
Function 44H (68) Subfunction 0AH (10) 
IOCTL: check if handle is remote 


Checks whether the specified handle refers to a file or device that is local (located on the PC that is 
running the program) or remote (located on a network server). 


Call with: AH = 44H 
AL = OAH 
BX = handle 
Returns: If function successful 
Carry flag =clear 
DX = attribute word for file or device 
bit 15 = 0 if local 
1 if remote 
If function unsuccessful 
Carry flag = set 
AX = error code 
Notes: = Application programs should not ordinarily attempt to distinguish between files on 


local and remote devices. 


m Ifthe network has not been started, control returns to the calling program with the 
carry flag set and error code 0001H (invalid function) in register AX. 
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Example: — Check if the handle saved in the variable fhandle is associated with a file or device on 
the machine running the program or on a network server. 


fhandle dw ? ; device handle 
mov ax,440ah ; function & subfunction 
mov bx, fhandle ; file/device handle 
int 21h ; transfer to MS-DOS 
je error ; jump if function failed 


and dx,8000h 
jnz remote 


test local/remote bit 
jump if network handle 


Int 21H [3.1] 
Function 44H (68) Subfunction 0BH (11) 
IOCTL: change sharing retry count 


Sets the number of times MS-DOS retries a disk operation after a failure caused by a file-sharing violation 
before it returns an error to the requesting process. This subfunction is not available unless the file- 
sharing module (SHARE.EXE) is loaded. 


Call with: AH = 44H 
AL = OBH 
CX = delays per retry (default = 1) 
DX = number of retries (default = 3) 
Returns: If function successful 


Carry flag =clear 

If function unsuccessful 
Carry flag =set 

AX = error code 


Notes: @ The length of a delay is a machine-dependent value determined by the CPU type 
and clock speed. Each delay consists of the following instruction sequence: 


xor CX,CX 
loop $ 
which executes 65,536 times before falling out of the loop. 


® The sharing retry count affects the behavior of the system as a whole and is not a 
local parameter for the process. If a program changes the sharing retry count, it 
should restore the default values before terminating. 
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Example: — Change the number of automatic retries for a file-sharing violation to five. 


mov ax,440bh ; function & subfunction 
mov cx,1 ; delays per retry 
mov dx,5 ; number of retries 
int 21h ; transfer to MS-DOS 
jc error ; jump if function failed 
Int 21H [3.2] 


Function 44H (68) Subfunction 0CH (12) 
IOCTL: generic I/O control for character devices 


Provides a general-purpose mechanism for communication between application programs and character- 
device drivers. 


Callwith: AH = 44H 
AL = 0CH 
BX = handle 
CH = category (major) code: 


OOH = unknown 
01H = COM1, COM2, COM3, or COM4 (3.3) 
03H = CON (keyboard and display) (3.3) 
05H = LPT1, LPT2, or LPT3 (3.2) 
CL = function (minor) code: 
45H = Set Iteration Count (3.2) 
4AH = Select Code Page (3.3) 
4CH = Start Code Page Preparation (3.3) 
4DH = End Code Page Preparation (3.3) 
5FH = Set Display Information (4.0) 
65H = Get Iteration Count (3.2) 
6AH = Query Selected Code Page (3.3) 
6BH = Query Prepare List (3.3) 
7FH = Get Display Information (4.0) 
DS:DX = segment:offset of parameter block 


Returns: If function successful 
Carry flag =clear 


and, if called with CL = 65H, 6AH, 6BH, or 7FH 
DS:DX = segment:offset of parameter block 
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If function unsuccessful 
Carry flag =set 
AX = error code 


Notes: ® Ifthe minor code is 45H (Set Iteration Count) or 65H (Get Iteration Count), the 
parameter block is simply a 2-byte buffer containing or receiving the iteration count 
for the printer. This call is valid only for printer drivers that support Output Until 
Busy, and determines the number of times the device driver will wait for the device 
to signal ready before returning from the output call. 

™ The parameter block for minor code 4DH (End Code Page Preparation) has the 
following format: 


dw 2 ; length of following data 
dw 0 ; (reserved) 


® For MS-DOS version 3.3, the parameter block for minor codes 4AH (Select Code 
Page) and 6AH (Query Code Page) has the following format: 


dw 2 ; length of following data 
dw ? ; code page ID 


For MS-DOS version 4.0, minor codes 4AH and 6AH also set or get the double-byte 
character set (DBCS) lead byte table, and the following format is used! 


dw (n+2)#*2+1 ; length of following data 
dw ? ; code page ID 

db start,end ; DBCS lead byte range 1 
db start,end ; DBCS lead byte range n 
db 0,0 


™ The parameter block for minor code 4CH (Start Code Page Preparation) has the 
following format: 


dw 0 ; font type 
; bit 0 = 0 downloaded 
: = ] cartridge 
; bits 1-15 = reserved (0) 

dw (n+1)#*2 ; length of remainder of 
: parameter block 

dw n ; number of code pages in 
; the following list 

dw ? ; code page l 

dw ? ; code page 2 

dw ? ; code page n 


™ The parameter block for minor code 6BH (Query Prepare List) has the following 
format, assuming 1 hardware code pages and m prepared code pages (n <= 12, 
m <= 12): 
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dw (n+m+2 ) «2 ; length of following data 


dw n ; number of hardware code pages 
dw ? ; hardware code page 1 
dw ? ; hardware code page 2 
dw ? ; hardware code page n 
dw m ; number of prepared code pages 
dw ? ; prepared code page 1 
dw ? ; prepared code page 2 
dw ? ; prepared code page m 


= After a minor code 4CH (Start Code Page Preparation) call, the data defining the 
code page font is written to the driver using one or more calls to the IOCTL Write 
Control Data subfunction (Interrupt 21H, Function 44H, Subfunction 03H). The for- 
mat of the data is device- and driver-specific. After the font data has been written to 
the driver, a minor code 4DH (End Code Page Preparation) call must be issued. If no 
data is written to the driver between the minor code 4CH and 4DH calls, the driver 
interprets the newly prepared code pages as hardware code pages. 


= A special variation of the minor code 4CH (Start Code Page Preparation) call, called 
“Refresh,” is required to actually load the peripheral device with the prepared code 
pages. The refresh operation is obtained by requesting minor code 4CH with each 
code page position in the parameter block set to -1, followed by an immediate call 
for minor code 4DH (End Code Page Preparation). 


@ [4.0+] For minor codes 5FH (Set Display Information) and 7FH (Get Display Informa- 
tion), the parameter block is formatted as follows: 


db 0 ; level (0 in MS-DOS 4.0) 
db 0 ; reserved (must be 0) 
dw 14 ; length of following data 
dw ? ; control flags 
; bit 0 = 0 intensity 
; = 1 blink 
; bits 1-15 = reserved (0) 
db ? ; mode type (1 = text, 2 = APA) 
db 0 ; reserved (must be 0) 
dw ? ; colors 


; 0 = monochrome compatible 
; 1 = 2 colors 

; 2 = 4 colors 

; 4 = 16 colors 

; 8 = 256 colors 


dw ? ; pixel columns 

dw ? ; pixel rows 

dw ? ; character columns 
dw ? ; character rows 
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Example: Get the current code page for the standard list device. 


stdprn equ 


pars dw 
dw 


mov 
mov 

‘mov 
mov 
mov 
mov 
mov 
int 
jc 


4 ; 


2 ; 


ax,440ch ; 
bx,stdprn ; 
ch,5 : 
cl,6ah ; 
dx,seg pars 

ds ,dx 
dx,offset pars 
21h 

error ; 


standard list handle 


length of data 
receives code page 


function & subfunction 
standard list handle 
LPTx category 

query code page 


; parameter block address 


; transfer to MS-DOS 


jump if function failed 


Int 21H 


[3.2] 


Function 44H Subfunction 0DH (13) 
IOCTL: generic I/O control for block devices 


Provides a general-purpose mechanism for communication between application programs and block- 
device drivers. Allows a program to inspect or change device parameters for a logical drive and to read, 
write, format, and verify disk tracks in a hardware-independent manner. 


Call with: AH 


DS:DX 


= 44H 
= 0ODH 


= drive code (0 = default, 1 = A, 2 = B, etc.) 


= category (major) code: 


O8H = disk drive 


= function (minor) code: 


40H = Set Device Parameters 


41H = Write Track 


42H = Format and Verify Track 
47H = Set Access Flag (4.0) 
GOH = Get Device Parameters 


61H = Read Track 
62H = Verify Track 


67H = Get Access Flag (4.0) 
= segment:offset of parameter block 
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Returns: 


If function successful 

Carry flag =clear 

and, if called with CL = 60H or 61H 

DS:DX = segment:offset of parameter block 
If function unsuccessful 

Carry flag =set 

AX = error code 


Notes: 


™ The minor code 40H (Set Device Parameters) function must be used before an at- 
tempt to write, read, format, or verify a track on a logical drive. In general, the 
following sequence applies to any of these operations: 


— Get the current parameters (minor code 60H). Examine and save them. 
— Set the new parameters (minor code 40H). 

— Perform the task. 

— Retrieve the original parameters and restore them with minor code 40H. 


™ For minor codes 40H (Set Device Parameters) and 60H (Get Device Parameters), the 
parameter block is formatted as follows: 


Special-functions field: offset OOH, length = 1 byte 

Bit(s) Value Meaning 

0 device BPB field contains a new default BPB 

use current BPB 

use all fields in parameter block 

use track layout field only 

sectors in track may be different sizes (should always be 
avoided) 

1 sectors in track are all same size; sector numbers range 
from 1 to the total number of sectors in the track (should 
always be used) 

3-7 —60 reserved 


Device type field: offset O1H, length 1 byte 
Value Meaning 

320/360 KB, 5.25-inch disk 
1.2 MB, 5.25-inch disk 

720 KB, 3.5-inch disk 
single-density, 8-inch disk 
double-density, 8-inch disk 
fixed disk 

tape drive 

other type of block device 


Device attributes field: offset O2H, length 1 word 
Bit(s) Value Meaning 


1 


oro KF © 


2 


SNM BR OQ DN — © 


) 0 removable storage medium 

1 nonremovable storage medium 
1 0 door lock not supported 

1 door lock supported 
2-15 0 reserved 
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Number of cylinders field: offset O4H, length 1 word 
Maximum number of cylinders supported on the block device 


Media type field: offset OOH, length.1 byte 


Value Meaning 
0 1.2 MB, 5.25-inch disk 
1 320/360 KB, 5.25-inch disk 


Device BPB field: offset O7H, length 31 bytes 

For format of the device BPB, see separate Note below. 

If bit 0 = 0 in special-functions field, this field contains the new default BPB for the 
device. 

If bit 0 = 1 in special-functions field, the BPB in this field is returned by the device 
driver in response to subsequent Build BPB requests. 


Track layout field: offset 26H, variable-length table 


Length Meaning 

Word number of sectors in track 
Word number of first sector in track 
Word size of first sector in track 
Word number of last sector in track 
Word size of last sectar in track 


The device BPB field is a 31-byte data structure that describes the current disk and 
its control areas. The field is formatted as follows: 


Byte(s) Meaning 

OOH-—01H bytes per sector 

02H sectors per cluster (allocation unit) 
03-04H reserved sectors, beginning at sector 0 

05H number of file allocation tables (FATs) 
06H-07H maximum number of root-directory entries 
08H-09H number of sectors 

OAH media descriptor 

OBH-OCH sectors per FAT 

ODH-OEFH - sectors per track 

OFH-10H number of heads 

11H-14H number of hidden sectors | 
15H-18H large number of sectors Gif bytes O8H-—09H=0) 
19H-1EH reserved 


When minor code 40H (Set Device Parameters) is used, the number of cylinders 
should not be altered, or some or all of the volume may become inaccessible. 


For minor codes 41H (Write Track) and 61H (Read Track), the parameter block is 
formatted as follows: 


Byte(s) Meaning 

00H special-functions field (must be 0) 
01H-—02H head 

03H—04H ~ cylinder 

05H-—06H starting sector 

07H—08H _ sectors to transfer 

O9H-—OCH transfer buffer address 


MS-DOS Functions Reference 


For minor codes 42H (Format and Verify Track) and 62H (Verify Track), the parame- 
ter block is formatted as follows: 


Byte(s) Meaning 


00H special-functions field 
Bit(s) Significance 
0 0 = Format/Verify track 
1 = Format status call (MS-DOS 4.0 only) 
1-7 reserved (0) 


01H-02H head 

03H-04H cylinder 

In MS-DOS 4.0, this function may be called with bit 0 of the special-functions field 
set after a minor code 40H call (Set Device Parameters) to determine whether the 
driver supports the specified number of tracks and sectors per track. A status is 
returned in the special-functions field which is interpreted as follows: 

Value Meaning 


0 specified number of tracks and sectors per track supported 

1; = this function not supported by the ROM BIOS 

2 specified number of tracks and sectors per track not supported 
3 no disk in drive 


For minor codes 47H (Set Access Flag) and 67H (Get Access Flag), the parameter 
block is formatted as follows: 


Byte Meaning 
00H special-functions field (must be 0) 
01H disk access flag 


When the disk access flag is zero, access to.the medium is blocked by the driver. The 
flag is set to zero when the driver detects an unformatted medium or a medium with 
an invalid boot record. When the access flag is nonzero, read/write operations to the 
medium are allowed by the driver. A formatting program must clear the disk access 
flag with minor code 47H before it requests minor code 42H (Format and Verify 
Track). 


Example: 
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Get the device parameter block for disk drive C. 

dbpb db 128 dup (0) ; device parameter block 
mov ax,440dh ; function & subfunction 
mov b1,3 ; drive C = 3 
mov ch,8 ; disk category 
mov c1,60h ; get device parameters 
mov dx,seg dbpb ; buffer address 
mov ds,dx 
mov dx,offset dbpb 
int 21h ; transfer to MS-DOS 
jc error ; jump if function failed 

Section IT 


Int 21H [3.2] 
Function 44H (68) Subfunction OEH (14) 
IOCTL: get logical drive map 


Returns the logical drive code that was most recently used to access the specified block device. 


Call with: AH = 44H 
. AL = OEH 
BL = drive code (0 = default, 1 = A, 2 = B, etc.) 
Returns: If function successful 
Carry flag =clear 
AL = mapping code 
OOH if only one logical drive code assigned to the block device 
01H-1AH logical drive code (1 = A, 2 = B, etc.) mapped to the block 
device 
If function unsuccessful 
Carry flag =set 
AX = error code 
Note: = Ifa drive has not been assigned a logical mapping with Function 44H Subfunction 


OFH, the logical and physical drive codes are the same. 


Example: —= Check whether drive A has more than one logical drive code. 


mov ax,440eh : function & subfunction 

mov bi,l ; drive 1=A 

int 21h ; transfer to MS-DOS 

jc error ; jump if function failed 
or al,al ; test drive code 

jz labell ; jump, no drive aliases 


é 
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Int 21H [3.2] 
Function 44H (68) Subfunction OFH (15) 
IOCTL: set logical drive map 


Sets the next logical drive code that will be used to reference a block device. 


Call with: AH = 44H 
AL = OFH 
BL = drive code (0 = default, 1 = A, 2 = B, etc.) 


Returns: If function successful 
Carry flag =clear 


AL = mapping code 
OOH if only one logical drive code assigned to the block device 
O1H—-1AH logical drive code (1 = A, 2 = B, etc.) mapped to the block 
device 
If function unsuccessful 
Carry flag = set 
AX = error code 


se es 
Note: = When a physical block device is aliased to more than one logical drive code, this 


function can be used to inform the driver which drive code will next be used to 
access the device. 


Example: Notify the floppy-disk driver that the next access will be for logical drive B. 


MOV ax,440fh ; function & subfunction 
mov b1,2 ; drive 2=B8B 

int 2ih ; transfer to MS-DOS 

je error ; jump if function failed 
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Int 21H [2.0] 
Function 45H (69) 
Duplicate handle 


Given a handle for a currently open device or file, returns a new handle that refers to the same device or 
file at the same position. 


Call with: AH = 45H 

BX = handle to be duplicated 
Returns: If function successful 

Carry flag =clear 

AX = new handle 


If function unsuccessful 
Carry flag =set 
AX = error code 


Notes: = Aseek, read, or write operation that moves the file pointer for one of the two 
handles also moves the file pointer associated with the other. 


= This function can be used to efficiently update the directory for a file that has 
changed in length, without incurring the overhead of closing and then reopening the 
file. The handle for the file is simply duplicated with this function and the duplicate 
is closed, leaving the original handle open for further read/write operations. 


= [3.3] See also Int 21H Function 68H (Commit File). 


Example: Duplicate the handle stored in the variable fhandle, then close the duplicate. This 
ensures that all buffered data is physically written to disk and that the directory entry for 
the corresponding file is updated, but leaves the original handle open for subsequent file 


operations. 
fhandle dw 0 ; file handle 
; get duplicate handle 
mov ah, 45h :; function number 
mov bx, fhandle ; original file handle 
int 21h ; transfer to MS-DOS 
jc error ; jump if dup failed 
; now close dup'd handle 
mov bDx,ax ; put handle into BX 
mov ah, 3eh ; function number 
int 21h ; transfer to MS-DOS 


(continued) 
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je error ; jump if close failed 


Int21H | [2.0] 
Function 46H (70) 


Redirect handle 
a ee eT 


Given two handles, makes the second handle refer to the same device or file at the same location as the 
first handle. The second handle is then said to be redirected. 


Call with: AH = 46H 
BX = handle for file or device 
CX = handle to be redirected 


Returns: If function successful 
Carry flag =clear 


If function unsuccessful 
Carry flag = set 


AX = error code 
i 
Notes: ™ Ifthe handle passed in CX already refers to an open file, that file is closed first. 


= A seek, read, or write operation that moves the file pointer for one of the two 
handles also moves the file pointer associated with the other. 


® This function is commonly used to redirect the standard input and output handles to 
another file or device before a child process is executed with Int 21H Function 4BH. 


a Cc or 


Example: Redirect the standard output to the list device, so that all output directed to the console 
will appear on the printer instead. Later, restore the original meaning of the standard 
output handle. 


stdin equ 0 
stdout equ 1 
stderr equ 2 
Stdaux equ 3 
stdprn equ 4 
dhandle dw 0 ; duplicate handle 
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; get dup of stdout 


mov ah, 45h ; function number 

mov bx, stdout ; standard output handle 

int 21h ; transfer to MS-DOS 

jc error ; jump if dup failed 

mov dhandle,ax ; save dup'd handle 
; redirect standard output 
; to standard list device 

mov ah,46h ; function number 

mov bx, stdprn ; standard list handle 

mov cx,stdout ; standard output handle 

int 21h ; transfer to MS-DOS 

jc error ; jump if redirect failed 
; restore standard output 
; to original meaning 

mov ah, 46h : function number 

mov bx,dhandle s saved duplicate handle 

mov cx, stdout ; standard output handle 

int 2ih ; transfer to MS-DOS 

jc error ; jump if redirect failed 
; close duplicate handle 
; because no longer needed 

mov ah,3eh ; function number 

mov bx,dhandle ; saved duplicate handle 

int 21h ; transfer to MS-DOS 

jc error ; jump if close failed 


Int 21H [2.0] 
Function 47H (71) 
Get current directory 


Obtains an ASCIIZ string that describes the path from the root to the current directory, and the name of 
that directory. 


Call with: AH = 47H 
DL = drive code (0 = default, 1 = A, etc.) 
DS:SI = segment:offset of 64-byte buffer 
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_—— OOOO rawr eee 


Returns: If function successful 
Carry flag =clear 


and buffer is filled in with full pathname from root of current directory. 


If function unsuccessful 

Carry flag =set 

AX = error code 
5 es 
Notes: = The returned path name does not include the drive identifier or a leading backslash 


(\). It is terminated with a null (00H) byte. Consequently, if the current directory is 
the root directory, the first byte in the buffer will contain OOH. 


™ The function fails if the drive code is invalid. 
= The current directory may be set with Int 21H Function 3BH. 


eee 
Example: Get the name of the current directory for drive C into the buffer named abuff. 


dbuff db 64 dup (0) ; receives path string 
mov ah,47h ; function number 
mov d1,03 ; drive C = 3 
mov si,seg dbuff ; buffer address 
mov ds,si 
mov si,offset dbuff 
int 21h ; transfer to MS-DOS 
jc error ; jump if error 


Se 
Int 21H [2.0] 


Function 48H (72) 
Allocate memory block 


Allocates a block of memory and returns a pointer to the beginning of the allocated area. 


Call with: AH = 48H 

BX = number of paragraphs of memory needed 
Returns: __If function successful 

Carry flag =clear 

AX = base segment address of allocated block 
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If function unsuccessful 
Carry flag =set 


AX = error code 
BX = size of largest available block (paragraphs) 
Notes: ™ If the function succeeds, the base address of the newly allocated block is AX:0000. 


—@ The default allocation strategy used by MS-DOS is “first fit’; that is, the memory 
block at the lowest address that is large enough to satisfy the request is allocated. 
The allocation strategy can be altered with Int 21H Function 58H. 


™ When a .COM program is loaded, it ordinarily already “owns” all of the memory 
in the transient program area, leaving none for dynamic allocation. The amount 
of memory initially allocated to a EXE program at load time depends on the 
MINALLOC and MAXALLOC fields in the .EXE file header. See Int 21H Function 
4AH. 


Example: Request a 64 KB block of memory for use as a buffer. 


bufseg dw ? ; segment base of new block 
mov ah,48h ; function number 
mov bx,1000h ; block size (paragraphs) 
int 2lh ; transfer to MS-DOS 
jc error ; jump if allocation failed 
mov bufseg,ax ; save segment of new block 


Le ee Sl 


Int 21H [2.0] 
Function 49H (73) 
Release memory block 


Releases a memory block and makes it available for use by other programs. 


Call with: AH = 49H 
ES = segment of block to be released 
Returns: If function successful 


Carry flag =clear 


If function unsuccessful 
Carry flag =set 
AX = error code 
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i is 
Notes: = This function assumes that the memory block being released was previously ob- 


tained by a successful call to Int 21H Function 48H. 
® The function will fail or can cause unpredictable system errors if: 
— the program releases a memory block that does not belong to it. 
~ the segment address passed in register ES is not a valid base address for an exist- 
ing memory block. 


is ee 
Example: Release the memory block that was previously allocated in the example for Int 21H Func- 


tion 48H (page 438). 

bufseg dw ? ; segment base of block 
mov ah,49h ; function number 
mov es, bufseg ; base segment of block 
int 21h *s transfer to MS-DOS 
jc error ; jump if release failed 


a eee eee 
Int 21H [2.0] 
Function 4AH (74) 


Resize memory block 
i 


Dynamically shrinks or extends a memory block, according to the needs of an application program. 


Callwith: AH = 44H 
BX = desired new block size in paragraphs 
ES = segment of block to be modified 


Returns: If function successful 
Carry flag =clear 


If function unsuccessful 
Carry flag = set 


AX = error code 

BX = maximum block size available (paragraphs) 
5 I es Se 
Notes: ™ This function modifies the size of a memory block that was previously allocated with 


a call to Int 21H Function 48H. 

™ Ifthe program is requesting an increase in the size of an allocated block, and this 
function fails, the maximum possible size for the specified block is returned in regis- 
ter BX. The program can use this value to determine whether it should terminate, or 
continue in a degraded fashion with less memory. 
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= A program that uses EXEC (int 21H Function 4BH) to load and execute a child pro- 
gram must call this function first to make memory available for the child, passing the 
address of its PSP in register ES and the amount of memory needed for its own code, 
data, and stacks in register BX. 


Example: Resize the memory block that was allocated in the example for Int 21H Function 48H 
(page 438), shrinking it to 32 KB. 


bufseg dw ? ; segment base of block 
mov ah, 4ah ; function number 
mov bx ,0800h ; new size (paragraphs) 
mov es, bufseg ; segment base of block 
int 21h ; transfer to MS-DOS 
jc error ; jump, resize failed 


Int 21H [2.0] 
Function 4BH (75) 
Execute program (EXEC) 


Allows an application program to run another program, regaining control when it is finished. Can also be 
used to load overlays, although this use is uncommon. 


Call with: AH = 4BH 
AL = subfunction 
OOH = Load and Execute Program 
03H = Load Overlay 


ES:BX = segment:offset of parameter block 

DS:DX = segment:offset of ASCIIZ program pathname 
Returns: If function successful 

Carry flag =clear 

[2] all registers except for CS:IP may be destroyed 

[3.0+] registers are preserved in the usual fashion 


If function unsuccessful 
Carry flag = set 
AX = error code 


MS-DOS Functions Reference 441 


Notes: = The parameter block format for Subfunction 00H (Load and Execute Program) is 
as follows: 
Bytes Contents 
QOH-—01H segment pointer to environment block 
02H-—03H offset of command line tail 
04H-05H segment of command line tail 
06H-07H offset of first FCB to be copied into new PSP + 5CH 
08H-09H segment of first FCB 
OAH-OBH offset of second FCB to be copied into new PSP + 6CH 
OCH-ODH segment of second FCB 


m The parameter block format for Subfunction 03H (Load Overlay) is as follows: 
Bytes Contents 
QOH-01H segment address where overlay is to be loaded 
02H-—03H _ relocation factor to apply to loaded image 


= The environment block must be paragraph-aligned. It consists of a sequence of 
ASCIIZ strings in the form: 


db "COMSPEC=A: \COMMAND.COM' ,0 


The entire set of strings is terminated by an extra null (OOH) byte. 


= The command tail format consists of a count byte, followed by an ASCII string, ter- 
minated by a carriage return (which is not included in the count). The first character 
in the string should be an ASCII space (20H) for compatibility with the command tail 
passed to programs by COMMAND.COM. For example: 


db 6,' *.DAT’,Odh 


= Before a program uses Int 21H Function 4BH to run another program, it must release 
all memory it is not actually using with a call to Int 21H Function 4AH, passing the 
segment address of its own PSP and the number of paragraphs to retain. 


= Ordinarily, all active handles of the parent program are inherited by the child pro- 
gram, although the parent can prevent this in MS-DOS 3.0 and later by setting the 
inheritance bit when the file or device is opened. Any redirection of the standard in- 
put and/or output in the parent process also affects the child process. 

= The environment block can be used to pass information to the child process. If the 
environment block pointer in the parameter block is zero, the child program inherits 
an exact copy of the parent’s environment. In any case, the segment address of the 
child’s environment is found at offset 002CH in the child’s PSP. 

m After return from the EXEC function call, the termination type and return code of 
the child program may be obtained with Int 21H Function 4DH. 


ee 
Example: — See Chapter 12. 
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Int 21H [2.0] 
Function 4CH (76) 
Terminate process with return code 


Terminates the current process, passing a return code to the parent process. This is one of several 
methods that a program can use to perform a final exit. MS-DOS then takes the following actions: 

m All memory belonging to the process is released. 

= File buffers are flushed and any open handles for files or devices owned by the 

process are closed. 

m The termination handler vector (Int 22H) is restored from PSP:000AH. 

m= The Ctrl-C handler vector (Int 23H) is restored from PSP:000EH. 

m (2.0+] The critical-error handler vector (Int 24H) is restored from PSP:0012H. 

= Control is transferred to the termination handler. 
If the program is returning to COMMAND.COM, control transfers to the resident portion and the transient 


portion is reloaded if necessary. If a batch file is in progress, the next line of the file is fetched and inter- 
preted; otherwise, a prompt is issued for the next user command. 


ee 


Call with: AH = 4CH 


AL = return code 


Ov 


Returns: Nothing 


em 


Notes: = ([2.0+] This is the preferred method of termination for application programs because 
it allows a return code to be passed to the parent program and does not rely on the 
contents of any segment register. Other methods of performing a final exit are: 

— Int 20H 
— Int 21H Function 00H 
— Int 21H Function 31H 
— Int 27H 
= Any files that have been opened using FCBs and modified by the program should be 
closed before program termination; otherwise, data may be lost. 


m The return code can be retrieved by the parent process with Int 21H Function 4DH 
(Get Return Code). It can also be tested in a batch file with an IF ERRORLEVEL 
statement. By convention, a return code of zero indicates successful execution, and a 
non-zero return code indicates an error. 

m (3.0+] If the program is running on a network, it should remove all locks it has 
placed on file regions before terminating. 
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_— rr eee 


Example: Terminate the current process, passing a return code of 1 to the parent process. 


mov ah,4ch ; function number 


mov al,Olh ; return code 
int 21h ; transfer to MS-DOS 


Se 
Int 21H [2.0] 


Function 4DH (77) 


Get return code 
rp rere 


Used by a parent process, after the successful execution of an EXEC call (Int 21H Function 4BH), to 
obtain the return code and termination type of a child process. 


Call with: AH = 4DH 
eee 
Returns: AH = exit type 

OOH if normal termination by Int 20H, Int 21H Function OOH, or 

Int 21H Function 4CH 

01H if termination by user's entry of CtrIDC 

02H if termination by critical-error handler 

03H if termination by Int 21H Function 31H or Int 27H 

AL = return code passed by child process (0 if child terminated by Int 20H, 
Int 21H Function 00H, or Int 27H) 


Notes: @ This function will yield the return code of a child process only once. A subsequent 
call without an intervening EXEC (Int 21H Function 4BH) will not necessarily return 
any valid information. 


= This function does not set the carry flag to indicate an error. If no previous child 
process has been executed, the values returned in AL and AH are undefined. 


Oe 


Example: Get the return code and termination kind of child process that was previously executed 
with Int 21H Function 4BH (EXEC). 


retcode dw ? >; return code, termination type 
mov ah,4dh ; function number 
int 2lh ; transfer to MS-DOS 
mov retcode,ax ; save child process info 
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Int 21H | [2.0] 
Function 4EH (78) 
Find first file 


a a Se 
Given a file specification in the form of an ASCIIZ string, searches the default or specified directory on 
the default or specified drive for the first matching file. 


Call with: AH = 4EH 

CX = search attribute (bits may be combined) 
Bit(s) Significance (if set) 
0 read-only 
1 hidden 
2 system 
3 volume label 
4 directory 
5 archive 
6-15 reserved (0) 

DS:DX = segment:offset of ASCIIZ pathname 


i SS SS 0005050008 


Returns: If function successful (matching file found) 
Carry flag =clear 
and search results returned in current disk transfer area as follows: 
Byte(s) Description 
OOH-14H reserved (0) 
15H attribute of matched file or directory 
16H-17H file time 
bits OOH—O4H = 2-second increments (0-29) 
bits OSH-OAH = minutes (0-59) 
bits OBH—OFH = hours (0-23) 
18H-19H file date 
bits OOH—04H = day (1-3) 
bits OSH—O8H = month (1-12) 
bits O9H—OFH = year (relative to 1980) 
1AH-—1DH file size 
1EH-2AH ASCIIZ filename and extension 
If function unsuccessful (no matching files) 
Carry flag =set 
AX = error code 


se a a 
Notes: = This function assumes that the DTA has been previously set by the program with Int 
21H Function 1AH to point to a buffer of adequate size. 


@ The « and? wildcard characters are allowed in the filename. If wildcard characters 
are present, this function returns only the first matching filename. 
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= Ifthe attribute is 0, only ordinary files are found. If the volume label attribute bit is 
set, only volume labels will be returned (if any are present). Any other attribute or 
combination of attributes (hidden, system, and directory) results in those files and 
all normal files being matched. 


Example: _ Find the first .COM file in the directory \MYDIR on drive C. 
fname db "C:\MYDIR\*.COM' ,0 


dbuff db 43 dup (0) ; receives search results 


set DTA address 


mov ah,lah ; function number 

mov dx,seg dbuff §; result buffer address 
mov ds,dx 

mov dx,offset dbuff 

int 21h ; transfer to MS-DOS 


; search for first match 


mov ah, 4eh ; function number 

mov cx,0 ; normal attribute 
mov dx,seg fname ; address of filename 
mov ds ,dx 

mov dx,offset fname 

int 21h ; transfer to MS-DOS 
jc error ; jump if no match 


——— 
Int 21H [2.0] 


Function 4FH (79) 
Find next file 


Assuming a previous successful call to Int 21H Function 4EH, finds the next file in the default or specified 
directory on the default or specified drive that matches the original file specification. 


i on i es a ss 
Call with: AH = 4FH 


Assumes DTA points to working buffer used by previous successful Int 21H Function 
4EH or 4FH. 


Returns: If function successful (matching file found) 
Carry flag =clear 


and search results returned in current disk transfer area as described for Int 21H 
Function 4EH 


446 ss Section I 


If function unsuccessful (no more matching files) 
Carry flag =set 
AX = error code 


I 
Notes: = Use of this call assumes that the original file specification passed to Int 21H Function 
4EH contained one or more * or ? wildcard characters. 


= When this function is called, the current disk transfer area (DTA) must contain infor- 
mation from a previous successful call to Int 21H Function 4EH or 4FH. 


I TS 
Example: Continuing the search operation in the example for Int 21H Function 4FH, find the next 
COM file Gif any) in the directory \MYDIR on drive C. 


fname db "C:\MYDIR\*.COM' ,0 


dbuff db 43 dup (0) - receives search results 


- search for next match 


mov ah,4fh - function number 
int 21h - transfer to MS-DOS 
jc error ; jump if no more files 


ae SS ns 


Int 21H 
Function 50H (80) 
Reserved 


ae 


a SS nn 


Int 21H 
Function 51H (81) 
Reserved 


2. ae 


a SS ns 


Int 21H 
Function 52H (82) 
Reserved 


ss. 
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——— 
Int 21H 


Function 53H (83) 
Reserved 
——— 


———— 
Int 21H [2.0] 


Function 54H (84) 
Get verify flag 


Obtains the current value of the system verify (read-after-write) flag. 


Sh 


Call with: AH = 54H 


Returns: AL = current verify flag value 
OOH if verify off 
O11 if verify on 
Notes: m Because read-after-write verification slows disk operations, the default state of the 
system verify flag is OFF. 


m The state of the system verify flag can be changed through a call to Int 21H Function 
2EH or by the MS-DOS commands VERIFY ON and VERIFY OFF. 


Example: Obtain the state of the system verify flag. 


Muv ah,54h ; function number 
int 21h ; transfer to MS-DOS 
cmp al,Olh ; check verify state 
je labell ; jump if verify on 


; else assume verify off 


————— 
Int 21H 


Function 55H (85) 
Reserved 


SSeS iSS SSS 
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Int 21H | | [2.0] 
Function 56H (86) 
Rename file 


a 
Renames a file and/or moves its directory entry to a different directory on the same disk. In MS-DOS 
version 3.0 and later, this function can also be used to rename directories. 


Call with: AH = 56H 
DS:DX = segment:offset of current ASCIIZ pathname 
ES:DI = segment:offset of new ASCIIZ pathname 
Returns: If function successful 


Carry flag =clear 


If function unsuccessful 
Carry flag =set 
AX = error code 


OO 


Notes: @ The function fails if: 


— any element of the pathname does not exist. 

— a file with the new pathname already exists. 

— the current pathname specification contains a different disk drive than does the 
new pathname. 

— the file is being moved to the root directory, and the root directory is full. 

— [3.0+] the program is running on a network and the user has insufficient access 
rights to either the existing file or the new directory. 


@ The « and? wildcard characters are not allowed in either the current or new 
pathname specifications. 


nO 


Example: Change the name of the file MYFILE.DAT in the directory \MYDIR on drive C to 
MYTEXT.DAT. At the same time, move the file to the directory \SYSTEM on the 


same drive. 
oldname db "C:\MYDIR\MYFILE.DAT',0O 
newname db "C: \SYSTEM\MYTEXT.DAT' ,0 
mov ah, 56h > function number 
mov dx,seg oldname ; old filename address 
mov ds ,dx 
mov dx,offset oldname 
mov di,seg newname ; new filename address 
mov es,di 
mov di,offset newname 


(continued) 


MS-DOS Functions Reference 449 


int 21h ; transfer to MS-DOS 
jc - error ; jump if rename failed 


ee 
Int 21H [2.0] 


Function 57H (87) 
Get or set file date and time 


Obtains or modifies the date and time stamp in a file’s directory entry. 


Call with: If getting date and time 


AH = 57H 

AL = 00H 

BX = handle 
If setting date and time 
AH = 57H 

AL = 01H 

BX = handle 
CX = time 


bits OOH—-04H = 2-second increments (0-29) 
bits OSH—OAH = minutes (0-59) 
bits OBH—OFH = hours (0-23) 
DX = date 
bits OOH-O4H = day (1-31) 
bits O5H—O8H = month (1-12) 
bits ONH—OFH = year (relative to 1980) 


Returns: If function successful 
Carry flag =clear 
and, if called with AL = 00H 
CX = time 
DX = date 
If function unsuccessful 
Carry flag = set 
AX = error code 


Notes: = The file must have been previously opened or created via a successful call to Int 21H 
Function 3CH, 3DH, 5AH, 5BH, or 6CH. 


= Ifthe 16-bit date for a file is set to zero, that file’s date and time are not displayed on 
directory listings. 

™ A date and time set with this function will prevail, even if the file is modified after- 
wards before the handle is closed. 
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a 


Example: 


Get the date that the file MYFILE.DAT was created or last modified, and then decom- 
pose the packed date into its constituent parts in the variables month, day, and year. 


fname 


month 
day 
year 


db 


mov 
mov 
mov 
mov 
mov 
int 
je 


mov 
mov 
mov 
int 
jc 


mov 
and 
mov 
shr 
mov 
and 
mov 
shr 
and 
add 
mov 


mov 
int 
jc 


"MYFILE.DAT’,O 


ah,3dh 
al,0 


dx,seg fname 


ds ,dx 


dx,offset fname 


21h 
error 


bx ,ax 
ah,57h 
al,0 
21h 
error 


day ,dx 
day ,Olfh 
cl,5 
dx,cl 
month, dx 
month,0fh 
cl,4 
dx,cl 

dx ,03fh 
dx, 1980 
year ,dx 


ah, 3eh 
21h 
error 


first open the file 
function number 
read-only mode 


> filename address 


- transfer to MS-DOS 


jump if open failed 


get file date/time 

copy handle to BX 
function number 

0 = get subfunction 
transfer to MS-DOS 

jump if function failed 


decompose date 
isolate day 


isolate month 


isolate year 
relative to 1980 
correct to real year 
save year 


now close file, 
handle still in BX 
function number 
transfer to MS-DOS 
jump if close failed 
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SSS 


Int 21H 


[3.0] 


Function 58H (88) 
Get or set allocation strategy 


Obtains or changes the code indicating the current MS-DOS strategy for allocating memory blocks. 


ns ee 


Call with: 


If getting strategy code 


AH = 58H 

AL = 00H 

If setting strategy code 

AH = 58H 

AL = 01H 

BX = desired strategy code 
OOH = first fit 
O1H = best fit 
O2H = last fit 


Sr ee 


Returns: 


Notes: 


Example: 


If function successful 

Carry flag =clear 

and, if called with AL = OOH 

AX = Current strategy code 
If function unsuccessful 

Carry flag = set 

AX = error code 


m= The memory allocation strategies are: 


— First fit: MS-DOS searches the available memory blocks from low addresses to 
high addresses, assigning the first one large enough to satisfy the block allocation 
request. 

— Best fit: MS-DOS searches all available memory blocks and assigns the smallest 
available block that will satisfy the request, regardless of its position. 

~ Last fit: MS-DOS searches the available memory blocks from high addresses to 
low addresses, assigning the highest one large enough to satisfy the block alloca- 
tion request. 


= The default MS-DOS memory allocation strategy is First Fit (code 0). 


Save the code indicating the current memory allocation strategy in the variable strat, 
then change the system’s memory allocation strategy to “best fit.” 


strat dw 0 ; previous strategy code 
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; get current strategy 


mov ah, 58h ; function number 

mov al ,0 ; 0 = get strategy 

int 21h ; transfer to MS-DOS 

jc error ; jump if function failed 
mov strat,ax ; save strategy code 


; now set new strategy 


mov ah,58h ; function number 

mov al,l ; 1 = set strategy 

mov bx,1 ; 1 = best fit 

int 21h ; transfer to MS-DOS 

jc error ; jump if function failed 


Int 21H [3.0] 
Function 59H (89) 
Get extended error information 


Obtains detailed error information after a previous unsuccessful Int 21H function call, including the 
recommended remedial action. 


Call with: AH = 59H 
BX = 00H 
Returns: AX = extended error code ~ 
01H function number invalid 
02H file not found 
03H path not found 
04H too many open files 
05H access denied 
06H handle invalid 
07H memory control blocks destroyed 
O8H insufficient memory 
OOH memory block address invalid 


OAH (10) — environment Invalid 

OBH (11) format invalid 

OCH (12) access code invalid 

ODH (13) data invalid 

OEH (14) unknown unit 

OFH (15) disk drive invalid 

10H (16) attempted to remove current directory 
11H (17) not same device 
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12H (18) 
13H (19) 
14H (20) 
15H (21) 
16H (22) 
17H (23) 
18H (24) 
19H (25) 
1AH (26) 
1BH (27) 
1CH (28) 
1DH (29) 
1EH G0) 
1FH BD 
20H (32) 
21H (33) 
22H (34) 
23H (35) 
24H (36) 
25H-31H 
32H (50) 
33H (51) 
34H (52) 
35H (53) 
36H (54) 
37H (55) 
38H (56) 
39H (57) 
3AH (58) 
3BH (59) 
3CH (60) 
3DH (61) 
3EH (62) 
3FH (63) 
40H (64) 
41H (65) 
42H (66) 
43H (67) 
44H (68) 
45H (69) 
46H (70) 
47H (7D 
48H (72) 
49H-—4FH 
50H (80) 
51H (81) 
52H (82) 
53H (83) 


no more files 

disk write-protected 

unknown unit 

drive not ready 

unknown command 

data error (CRC) 

bad request structure length 
seek error 

unknown media type 

sector not found 

printer out of paper 

write fault 

read fault 

general failure 

sharing violation 

lock violation 

disk change invalid 

FCB unavailable 

sharing buffer exceeded 
reserved 

unsupported network request 
remote machine not listening 
duplicate name on network 
network name not found 
network busy 

device no longer exists on network 
netBIOS command limit exceeded 
error in network adapter hardware 
incorrect response from network 
unexpected network error 
remote adapter incompatible 
print queue full 

not enough space for print file 
print file canceled 

network name deleted 

network access denied 

incorrect network device type 
network name not found 
network name limit exceeded 
netBIOS session limit exceeded 
Jile sharing temporarily paused 
network request not accepted 
print or disk redirection paused 
reserved 

Jule already exists 

reserved 

cannot make directory 

Jail on Int 24H (critical error) 


BH 


BL 


CH 


54H (8H 
55H (85) 
56H (86) 
57H (87) 
58H (88) 
59H (89) 
5AH (90) 


error class 
01H 
02H 


03H 
04H 
05H 
06H 


O7H 
08H 
O9H 
OAH (10) 
OBH (11) 


OCH (12) 
ODH (13) 


too many redirections 

duplicate redirection 

invalid password 

invalid parameter 

network device fault 

function not supported by network 
required system component not installed 


if out of resource (such as storage or handles) 

if not error, but temporary situation (such as locked region 
in file) that can be expected to end 

if authorization problem 

if internal error in system software 

if hardware failure 

if system software failure not the fault of the active process 
(such as missing configuration files) 

if application program error 

if file or item not found 

if file or item of invalid type or format 

if file or item locked 

if wrong disk in drive, bad spot on disk, or storage medium 
problem 

if item already exists 

unknown error 


recommended action 


01H 


02H 


03H 


04H 


O5H 
06H 
O7H 


error locus 
O1H 
O2H 
03H 
04H 
05H 


retry reasonable number of times, then prompt user to 
select abort or ignore 

retry reasonable number of times with delay between 
retries, then prompt user to select abort or ignore 

get corrected information from user (typically caused by 
incorrect filename or drive specification) 

abort application with cleanup (i.e., terminate the 
program in as orderly a manner as possible: releasing 
locks, closing files, etc.) 

perform immediate exit without cleanup 

ignore error 

retry after user intervention to remove cause of error 


unknown 

block device (disk or disk emulator) 
network 

serial device 

memory 


and, for MS-DOS 3.0 and later, 
= ASCIIZ volume label of disk to insert, if AX = 0022H (invalid 


ES:DI 


disk change) 
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Notes: m =This function may be called after any other Int 21H function call that returned an er- 
ror status, in order to obtain more detailed information about the error type and the 
recommended action. If the previous Int 21H function call had no error, 0000H is 
returned in register AX. This function may also be called during the execution of a 
critical-error (Int 24H) handler. 


# The contents of registers CL, DX, SI, DI, BP, DS, and ES are destroyed by this 
function. 

= Note that extended error codes 13H-1FH (19-31) and 34 (22H) correspond exactly 
to the error codes 0O—OCH (0-12) and OFH (15) returned by Int 24H. 

= You should not code your programs to recognize only specific error numbers if you 


wish to ensure upward compatibility, because new error codes are added in each 
version of MS-DOS. 


eee 
Example: Attempt to open the file named NOSUCH.DAT using a file control block; if the open 
request fails, get the extended error code. 


myfcb db 0 ; drive = default 
db *NOSUCH ' ; filename, 8 chars 
db ‘DAT’ ; extension, 3 chars 
db 25 dup (0) ; remainder of FCB 
labell: ; open the file 
mov ah,Ofh ; function number 
mov dx,seg myfcb ; address of FCB 
mov ds ,dx 
mov dx,offset myfcb 
int 21h ; transfer to MS-DOS 
or al,al ; check open status 
jz | success ; jump if opened OK 


; open failed, get 
; extended error info 


mov ah, 59h function number 


xor bx, bx ; BX must = 0 

int 21h ; transfer to MS-DOS 

or ax,ax ; double check for error 
jz success ; jump if no error 

cmp b1,2 ; Should we retry? 

jle labell ; yes, jump 

jmp error ; no, give up 
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Int 21H [3.0] 
Function 5AH (90) 
Create temporary file 


Creates a file with a unique name, in the current or specified directory on the default or specified disk 
drive, and returns a handle that can be used by the program for subsequent access to the file. The name 
generated for the file is also returned in a buffer specified by the program. 


Call with: AH = 5AH 
CX = attribute (bits may be combined) 
Bit(s) Significance (if set) 
0 read-only 
1 hidden 
2 system 
3-4 reserved (0) 
5 archive 
6-15 reserved (0) 
DS:DX = segment:offset of ASCIIZ path 
Returns: If function successful 
Carry flag =clear 
AX = handle 
DS:DX = segment:offset of complete ASCIIZ pathname 
If function unsuccessful 
Carry flag = set 
AX = error code 
Notes: ™ The ASCIIZ path supplied to this function should be followed by at least 13 addi- 


tional bytes of buffer space. MS-DOS adds a backslash (\) to the supplied path, if 
necessary, then appends a null-terminated filename that is a function of the current 
time. 


@ Files created with this function are not automatically deleted when the calling pro- 
gram terminates. 


@ The function fails if 


— any element of the pathname does not exist. 
— the file is being created in the root directory, and the root directory is full. 


® See also Int 21H Functions 3CH, 5BH, and 6CH, which provide additional facilities 
for creating files. 


@ (3.0+] If the program is running on a network, the file is created and opened for 
read/write access in compatibility sharing mode. 
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I ee 
Example: Create a temporary file with a unique name and normal attribute in directory \TEMP of 


drive C. Note that you must allow room for MS-DOS to append the generated filename to 
the supplied path. The complete file specification should be used to delete the tempo- 
rary file before your program terminates. 


fname db "C:\TEMP\' ; pathname for temp file 
db 13 dup (0) ; receives filename 
fhandle dw ? ; file handle 


mov ah,5ah ; function number 

mov cx,0 ; normal attribute 

mov dx,seg fname’ ; address of pathname 
mov ds ,dx 

mov dx,offset fname 

int 21h ; transfer to MS-DOS 

jc error ; jump if create failed 
mov fhandle,ax ; save file handle 


a ee ee 
Int 21H [3.0] 


Function 5BH (91) 


Create new file 
a a a a ee ee 


Given an ASCIIZ pathname, creates a file in the designated or default directory on the designated or 
default drive, and returns a handle that can be used by the program for subsequent access to the file. If a 
file with the same name already exists, the function fails. 


Call with: AH = 5BH 

CX = attribute (bits may be combined) 
Bit(s) Significance (if set) 
0 read-only 
1 hidden 
2 system 
3 volume label 
4 reserved (0) 
5 archive 
6-15 reserved (0) 

DS:DX = segment:offset of ASCIIZ pathname 
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Returns: 


Notes: 


Example: 


If function successful 


Carry flag 
AX 


= clear 
= handle 


If function unsuccessful 


Carry flag 
AX 


= error code 


™ The function fails if: 


— any element of the specified path does not exist. 
— a file with the identical pathname (i.e., the same filename and extension in the 
same location in the directory structure) already exists. 


— the file is being created in the root directory, and the root directory is full. 


— [3.0+] the program is running on a network, and the user has insufficient access 
rights to the directory that will contain the file. 


® The file is usually given a normal attribute (0) when it is created, and is opened for 
both read and write operations. The attribute can subsequently be modified with Int 
21H Function 43H. 


™ See also Int 21H Functions 3CH, 5AH, and 6CH, which provide alternative ways of 


creating files. 


= This function may be used to implement semaphores in a network or multitasking 
environment. If the function succeeds, the program has acquired the semaphore. To 
release the semaphore, the program simply deletes the file. 


Create and open a file named MYFILE.DAT in the directory \MYDIR on drive C, 


MS-DOS returns an error if a file with the same name already exists in that location. 


"C:\MYDIR\MYFILE.DAT’ ,0 


fname db 


fhandle dw 


mov 
xor 
mov 
mov 
mov 
int 
jc 

mov 


ah,5bh ; 
Cx,CX : 
dx,seg fname ; 
ds ,dx 

dx,offset fname 
21h ; 
error ; 
fhandle,ax : 


file handle 


function number 
normal attribute 
filename address 


transfer to MS-DOS 
jump if create failed 
save file handle 
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Int 21H [3.0] 
Function 5CH (92) 
Lock or unlock file region 


Locks or unlocks the specified region of a file. This function is not available unless the file-sharing 
module (SHARE.EXE) is loaded. 


Call with: AH = 5CH 
AL = 00H if locking region 
01H if unlocking region 
BX = handle ARQ BAY 
CX = high part of region offset 59 
DX = low part of region offset 5°” 
SI = high part of regionlength  “‘) 
DI = low part of region length \2 
Returns: If function successful 


Carry flag =clear 

If function unsuccessful 
Carry flag = set 

AX = error code 


Notes: ® This function is useful for file and record synchronization in a multitasking environ- 
ment or network. Access to the file as a whole is controlled by the attribute and file- 
sharing parameters passed in open or create calls and by the file’s attributes, which 
are stored in its directory entry. 


= The beginning location in the file to be locked or unlocked is supplied as a positive 
double precision integer, which is a byte offset into the file. The length of the region 
to be locked or unlocked is similarly supplied as a positive double precision integer. 

= For every call to lock a region of a file, there must be a subsequent unlock call with 
exactly the same file offset and length. 

™ Locking beyond the current end of file is not an error. 


™ Duplicate handles created with Int 21H Function 45H, or handles redirected to the 
file with Int 21H Function 46H, are allowed access to locked regions within the same 
process. 

™ Programs that are loaded with the EXEC call (Int 21H Function 4BH) inherit the 
handles of their parent but not any active locks. 

= Ifa process terminates without releasing active locks on a file, the result is un- 
defined. Therefore, programs using this function should install their own Int 23H 
and Int 24H handlers so that they cannot be terminated unexpectedly. 
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Example: Assume that a file was previously opened and that its handle was saved in the variable 
Shandle. Lock a 4096 byte region of the file, starting at 32,768 bytes from the beginning 
of the file, so that it cannot be accessed by other programs. 


fhandle dw ? ; file handle 
mov ah,5ch ; function number 
mov al,0 ; subfunction 0 = lock 
mov bx,fhandle ; file handle é 
mov cx,0 ; upper part of offset 
mov dx ,32768 ; lower part of offset 
mov si,0 ; upper part of length 
mov di,4096 ; lower part of length 
int 21h ; transfer to MS-DOS 
jc error ; jump if lock failed 


Int 21H 
Function 5DH (93) 
Reserved 


Int 21H [3.1] 
Function 5EH (94) Subfunction 00H 
Get machine name 


Returns the address of an ASCIIZ (null-terminated) string identifying the local computer. This function 
call is only available when Microsoft Networks is running. 


Call with: AH = 5EH 

AL = 00H 

DS:DX = segment:offset of buffer to receive string 
Returns: If function successful 

Carry flag = clear 

CH = 0OH if name not defined 

<> 00H if name defined 
CL = netBIOS name number (if CH <> 0) 
DxX:DX = segment:offset of identifier Gf CH <> 0 ) 
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If function unsuccessful 
Carry flag = set 
AX = error code 


Notes: ® The computer identifier is a 15-byte string, padded with spaces and terminated with 
a null (00H) byte. 


= The effect of this call is unpredictable if the file-sharing support module is not 
loaded. 


Example: Get the machine name of the local computer into the buffer named mname. 


mname db 16 dup (?) 
mov ax,5e00h ; function & subfunction 
mov dx,seg mname ; address of buffer 
mov ds,dx 
mov dx,offset mname 
int 2ih ; transfer to MS-DOS 
je error ; jump if function failed 
or ch,ch ; make sure name exists 
jz error ; jump if no name defined 


Int 21H [3.1] 
Function 5EH (94) Subfunction 02H 
Set printer setup string 


Specifies a string to be sent in front of all files directed to a particular network printer, allowing users at 
different network nodes to specify individualized operating modes on the same printer. This function call 
is only available when Microsoft Networks is running. 


Call with: AH = 5EH 

AL = 02H 

BX = redirection list index 

CX = length of setup string 

DS:SI = segment:offset of setup string 
Returns: If function successful 


Carry flag =clear 
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If function unsuccessful 
Carry flag = set 
AX = error code 


Notes: a The redirection list index passed in register BX is obtained with Function 5FH Sub- 
function 02H (Get Redirection List Entry). 


m See also Function 5EH Subfunction 03H, which may be used to obtain the existing 
setup string for a particular network printer. 


Example: Initialize the setup string for the printer designated by redirection list index 2 so that the 
device is put into boldface mode before printing a file requested by this network node. 


setup db O1bh,045h ; selects boldface mode 
mov ax,5e02h ; function & subfunction 
mov bx,2 ; redirection list index 2 
mov Cx,2 ; length of setup string 
mov si,seg setup ; address of setup string 
mov ds,si 
mov si,offset setup 
int 21h ; transfer to MS-DOS 
jc error ; jump if function failed 


Int 21H [3.1] 
Function 5EH (94) Subfunction 03H 
Get printer setup string 


Obtains the printer setup string for a particular network printer. This function call is only available when 
Microsoft Networks is running. 


Call with: AH = 5EH 

AL = 03H 

BX = redirection list index 

ES:DI = segment:offset of buffer to receive setup string 
Returns: If function successful 

Carry flag =clear 

CX = length of printer setup string 

ES:DI = address of buffer holding setup string 
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Notes: 


If function unsuccessful 
Carry flag =set 
AX = error code 


™ The redirection list index passed in register BX is obtained with Function 5FH Sub- 
function 02H (Get Redirection List Entry). 

@ See also Int 21H Function 5EH Subfunction 02H, which is used to specify a setup 
string for a network printer. 


Example: 


Get the setup string for this network node associated with the printer designated by re- 
direction list index 2. 


setup db 64 dup (7?) ; receives setup string 
mov ax,5e03h ; function & subfunction 
mov bx,2 ; redirection list index 2 
mov di,seg setup ; address of buffer 
mov es,di 
mov di,offset setup 
int 2lh ; transfer to MS-DOS 
jc error ; jump if function failed 


Int 21H 


[3.1] 


Function 5FH (95) Subfunction 02H 
Get redirection list entry 


Allows inspection of the system redirection list, which associates local logical names with network files, 
directories, or printers. This function call is only available when Microsoft Networks is running and the 
file-sharing module (SHARE.EXE) has been loaded. 


Call with: 


Returns: 


AH = 5FH 

AL = 02H 

BX = redirection list index 

DS:SI = segment:offset of 16-byte buffer to receive local device name 
ES:DI = segment:offset of 128-byte buffer to receive network name 


If function successful 
Carry flag =clear 
BH = device status flag 
bit O = 0 if device valid 
= 1 if not valid 
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BL = device type 
03H if printer 
04H if drive 


CX = stored parameter value 

DX = destroyed 

BP = destroyed 

DS:SI = segment:offset of ASCIIZ local device name 
ES:DI = segment:offset of ASCIIZ network name 


If function unsuccessful 
Carry flag =set 
AX = error code 


Note: m The parameter returned in CX is a value that was previously passed to MS-DOS in 
register CX with Int 21H Function 5FH Subfunction 03H (Redirect Device). It repre- 
sents data that is private to the applications which store and retrieve it and has no 
meaning to MS-DOS. 


Example: Get the local and network names for the device specified by the first redirection 


list entry. 
local db 16 dup (7?) ; receives local device name 
network db 128 dup (7?) ; receives network name 
mov ax, 5f02h : function & subfunction 
mov bx,0 ; redirection list entry 0 
mov si,seg local : local name buffer addr 
mov ds,si 
mov si,offset local 
mov di,seg network ; network name buffer addr 
mov es,di 
mov di,offset network 
int 21h ; transfer to MS-DOS 
jc error ; jump if call failed 
or bh, bh ; check device status 
jnz error ; jump if device not valid 
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Int 21H | [3.1] 
Function 5FH (95) Subfunction 03H 
Redirect device 


Establishes redirection across the network by associating a local device name with a network name. This 
function call is only available when Microsoft Networks is running and the file-sharing module 
(SHARE.EXE) has been loaded. 


Call with: AH = 5FH 
AL = 03H 
BL = device type 


03H if printer 
04H if drive 


CX = parameter to save for caller 
DS:SI = segment:offset of ASCIIZ local device name 
ES:DI = segment:offset of ASCIIZ network name, followed by ASCIIZ password 


Returns: If function successful 
Carry flag =clear 


If function unsuccessful 
Carry flag = set 
AX = error code 


eee 
Notes: a The local name can be a drive designator (a letter followed by a colon, such as “D:”), 


a printer name, or a null string. Printer names must be one of the following: PRN, 
LPT1, LPT2, or LPT3. If a null string followed by a password is used, MS-DOS at- 
tempts to grant access to the network directory with the specified password. 

m The parameter passed in CX can be retrieved by later calls to Int 21H Function 5FH 
Subfunction 02H. It represents data that is private to the applications which store 
and retrieve it and has no meaning to MS-DOS. 


Example: _ Redirect the local drive E to the directory \FORTH on the server named LMI, using the 


password FRED. 
Tocname db "E:',0 ; local drive 
netname db "\\LMI\FORTH’ ,0 

db *FRED' ,0 
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mov ax, 5f03h - function & subfunction 


mov b1,4 ; code 4 = disk drive 

mov si,seg locname ; address of local name 
mov ds,si 

mov si,offset locname 

mov di,seg netname ; address of network name 
mov es,di 

mov di,offset netname 

int 2lh ; transfer to MS-DOS 

jc error ; jump if redirect failed 


Int 21H [3.1] 
Function 5FH (95) Subfunction 04H 

Cancel device redirection 

a 
Cancels a previous redirection request by removing the association of a local device name with a network 


name. This function call is only available when Microsoft Networks is running and the file-sharing 
module (SHARE.EXE) has been loaded. 


Call with: AH = 5FH 

AL = 04H 

DS:SI = segment:offset of ASCIIZ local device name 
Returns: If function successful 


Carry flag =clear 

If function unsuccessful 
Carry flag =set 

AX = error code 


Note: = The supplied name can be a drive designator (a letter followed by a colon, such as 
“D:”), a printer name, or a string starting with two backslashes (\\). Printer names 
must be one of the following: PRN, LPT1, LPT2, or LPT3. If the string with two 
backslashes is used, the connection between the local machine and the network 
directory is terminated. 


Example: Cancel the redirection of local drive E to the network server. 


locname db "E:',0 


(continued) 
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mov ax,5f04h ; function & subfunction 


mov si,seg locname ; address of local name 
mov ds,si 

mov si,offset locname 

int 2ih ; transfer to MS-DOS 

jc error ; jump if cancel failed 


Function 60H (96) 
Reserved 


Reserved 


Function 62H (98) 
Get PSP address 


Obtains the segment (paragraph) address of the program segment prefix (PSP) for the currently execut- 
ing program. 


Callwith: AH = 62H 

Returns: BX = segment address of program segment prefix 
i 
Notes: = Before a program receives control from MS-DOS, its program segment prefix is set 


up to contain certain vital information, such as: 


— the segment address of the program’s environment block 
— the command line originally entered by the user 
— the original contents of the terminate, Ctrl-C, and critical-error handler vectors 
— the top address of available RAM 

= The segment address of the PSP is normally passed to the program in registers DS 
and ES when it initially receives control from MS-DOS. This function allows a pro- 
gram to conveniently recover the PSP address at any point during its execution, 

, without having to save it at program entry. 
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Example: Get the segment base of the program segment prefix, then copy the command tail from 
the PSP into the local buffer named buff. 


ctail equ 080H ; PSP offset, command tail 


buff db 80 dup (7?) ; copy of command tail 


; get PSP address 
mov ah,62H : function number 
int 21h : transfer to MS-DOS 


: copy command tail 


mov ds ,bx ; PSP segment to DS 

mov si,offset ctail ; offset of command tail 
mov di,seg buff ; local buffer address 
mov es ,di 

mov di,offset buff 

mov cl,Csi] ; length of command tail 
inc cl : include count byte 
xor ch,ch 

cld 

rep movsb ; copy to local buffer 


Int 21H [2.25 only] 
Function 63H (99) 
Get DBCS lead byte table 


Obtains the address of the system table of legal lead byte ranges for double-byte character sets (DBCS), or 
sets or obtains the interim console flag. Int 21H Function 63H is available only in MS-DOS version 2.25; it 
is not supported in MS-DOS versions 3.0 and later. 


Call with: AH = 63H 

AL = subfunction 
OOH if getting address of DBCS lead byte table 
O1H if setting or clearing interim console flag 
02H if obtaining value of interim console flag 

If AL = 01H 

DL = 00H if clearing interim console flag 
01H if setting interim console flag 
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Oe —— ————————— —— .. 


Returns: If function successful 
Carry flag =clear 


and, if called with AL = 00H 


DS:SI = segment:offset of DBCS lead byte table 
or, if called with AL = 02H 
DL = value of interim console flag 


If function unsuccessful 
Carry flag = set 
AX = error code 


Notes: m= The DBCS lead byte table consists of a variable number of two byte entries, termi- 
nated by two null (00H) bytes. Each pair defines the beginning and ending value for 
a range of lead bytes. The value of a legal lead byte is always in the range 80—OFFH. 
= Entries in the lead byte table must be in ascending order. If no legal lead bytes are 
defined in a given system, the table consists only of the two null bytes. 

m Ifthe interim console flag is set, Int 21H Functions 07H (Unfiltered Character Input), 
08H (Character Input without Echo), and OBH (Keyboard Status) will support interim 
characters. 

= Unlike most other MS-DOS services, this function call does not necessarily preserve 
any registers except SS:SP. 

= [4.0] The address of the DBCS lead byte table can also be obtained with Int 21H 
Function 65H. 


Int 21H 
Function 64H (100) 
Reserved 


Int 21H — «*(B.3] 
Function 65H (01 
Get extended country information 


Obtains information about the specified country and/or code page. 


Call with: AH = 65H 
AL = subfunction 
O1H = Get General Internationalization Information 
02H = Get Pointer to Uppercase Table 
04H = Get Pointer to Filename Uppercase Table 
OGH = Get Pointer to Collating Table 
O7H = Get Pointer to Double-Byte Character Set (DBCS) Vector 
(MS-DOS versions 4.0 and later) 


470 Section IT 


BX = code page of interest (-1 = active CON device) 


CX = length of buffer to receive information (must be >= 5) 
DX = country ID (—1 = default) 
ES:DI = address of buffer to receive information 


a naa EEE Enns 


Returns: 


If function successful 
Carry flag =clear 


and requested data placed in calling program’s buffer 
If function unsuccessful 


Carry flag = set 
AX = error code 


a 


Notes: 


a The information returned by this function is a superset of the information returned 
by Int 21H Function 38H. 


= This function may fail if either the country code or the code page number is invalid, 
or if the code page does not match the country code. 


= The function fails if the specified buffer length is less than five bytes. If the buffer to 
receive the information is at least five bytes long but is too short for the requested 
information, the data is truncated and no error is returned. 


m= The format of the data returned by Subfunction 01H is: 
Byte(s) Contents 
OOH information ID code (1) 
01H-02H length of following buffer 
03H-04H country ID 
OSH-06H code page number 
07H-—08H date format 
O= USA may 
1=Europe dmy 
2=jJapan ymd 
O9H-ODH_ ASCIIZ currency symbol 
OEH-OFH  ASCIIZ thousands separator 
10H-11H ASCIIZ decimal separator 
12H-13H  ASCIIZ date separator 
14H-15H  ASCIIZ time separator 


16H currency format flags 
bit O =0 if currency symbol precedes value 
=1 if currency symbol follows value 
bit 1 =0 if no space between value and currency symbol 
=1 if one space between value and currency symbol 
bit 2 =0 if currency symbol and decimal are separate 
=1 if currency symbol replaces decimal separator 
17H number of digits after decimal in currency 
18H time format 
bit O =0 if 12-hour clock 


=1 if 24-hour clock 
19H-1CH __case-map routine call address 
1DH-1EH ASCIIZ data list separator 
1FH-28H reserved 
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a The format of the data returned by Subfunctions 02H, 04H, 06H, and 07H is: 
Byte(s) Contents 
00H information ID code (2, 4, or 6) 
01H-05H = double-word pointer to table 


= The uppercase and filename uppercase tables are a maximum of 130 bytes long. The 
first two bytes contain the size of the table; the following bytes contain the upper- 
case equivalents, if any, for character codes 80H-FFH. The main use of these tables 
is to map accented or otherwise modified vowels to their plain vowel equivalents. 
Text translated with the help of this table can be sent to devices that do not support 
the IBM graphics character set, or used to create filenames that do not require a spe- 
cial keyboard configuration for entry. 


= The collating table is a maximum of 258 bytes long. The first two bytes contain the 
table length, and the subsequent bytes contain the values to be used for the corre- 
sponding character codes (0O—FFH) during a sort operation. This table maps 
uppercase and lowercase ASCII characters to the same collating codes so that sorts 
will be case-insensitive, and it maps accented vowels to their plain vowel 
equivalents. 


w [4.0+] Subfunction 07H returns a pointer to a variable length table of that defines 


ranges for double-byte character set (DBCS) lead bytes. The table is terminated bya 
pair of zero bytes, unless it must be truncated to fit in the buffer, and has the follow- 


ing format: 
dw length 
db startl,endl 
db start2,end2 
db 0,0 

For example: 
dw 4 
db 81h,9fh 
db Oe0h,0fch 
db 0,0 


= In some cases a truncated translation table may be presented to the program by 
MS-DOS. Applications should always check the length at the beginning of the table, 
to make sure it contains a translation code for the particular character of interest. 


 _ ChCO rho or ee 


Examples: Obtain the extended country information associated with the default country and code 
page 437. 
buffer db 41 dup (0) ; receives country info 
mov ax,6501h ; function & subfunction 
mov bx ,437 ; code page 
472 = Section IT 


mov 
mov 
mov 
mov 
mov 
int 
jc 


cx,41 

dx,-1l 

di,seg buffer 
es,di 

di,offset buffer 
21h 

error 


buffer length 
default country 
buffer address 


; transfer to MS-DOS 
; jump if function failed 


In this case, MS-DOS filled the following extended country information into the buffer: 


buffer 


db 
dw 
dw 
dw 
dw 
db 
db 
db 
db 
db 
db 
db 
db 
dd 
db 
db 


1 

38 

1 

437 

0 
"$',0,0,0,0 
era | 

et) 

set 20 

FeO 

0 

2 

0 
026ah:176ch 
eae | 

10 dup (0) 


info ID code 

length of following buffer 
country ID (USA) 

code page number 

date format 

currency symbol 
thousands separator 
decimal separator 
date separator 

time separator 
currency format flags 
digits in currency 
time format 

case map entry point 
data list separator 
reserved 


Obtain the pointer to the uppercase table associated with the default country and code 
page 437. 


buffer 


db 


mov 
mov 
mov 
mov 
mov 
mov 
mov 
int 
jc 


5 dup (0) 


ax,6502h 

bx ,437 

cx,5 

dx,-l 

di,seg buffer 
es,di 

di,offset buffer 
21h 

error 


receives pointer info 


function number 

code page 

length of buffer 
default country 

buffer address 


transfer to MS-DOS 
jump if function failed 
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In this case, MS-DOS filled the following values into the buffer: 


buffer 


and the table at 1140:0204H contains the following data: 


23 45 67 8 9 A BC D €E F 0123456789ABCDEF 
1140: 
:0210 
70220 
1140: 
1140: 
1140: 


1140 
1140 


1140 


1140 


Int 21H 


0200 


0230 
0240 
0250 


70260 
1140: 
:0280 


0270 


db 
dw 
dw 


2 
0204h 
1140h 


0 1 


45 
9A 
AA 
BA 
CA 
DA 
EA 
FA 


Function 66H (102) 
Get or set code page 


SSS Sissies 


Obtains or selects the current code page. 


TC SEE 


Call with: AH = 66H 
AL = subfunction 
BX 
Returns: If function successful 
Carry flag =clear 
and, if called with AL = 01H 
BX = active code page 
DX = default code page 
If function unsuccessful 
Carry flag = set 
AX = error code 


OO eee 


™ When the Select Code Page subfunction is used, MS-DOS gets the new code page 


Note: 


80 
BE 
9E 
AE 
BE 
CE 
DE 
EE 
FE 


00 
8F 
OF 
AF 
BF 
CF 
DF 
EF 
FF 


80 
90 
41 
BO 
CO 
DO 
EO 
FO 


; info ID code 
; offset of uppercase table 
; segment of uppercase table 


O1H = Get Code Page 
02H = Select Code Page 
= code page to select, if AL = 02H 


45 
92 
4F 
B2 
C2 
D2 
E2 
F2 


41 
4F 
55 
B3 
C3 
D3 
E3 
F3 


8E 
99 
A5 
B4 
C4 
D4 
E4 
F4 


41 


8F 
55 
A6 
B6 
C6 
D6 
E6 
F6 


80 
55 
A7 
B7 
C7 
D7 
E7 
F7 


45 
59 
A8 
B8 
C8 
D8 
E8 
F8 


45 oesbAsA.. EE 
99! VET LT canes 0.QUUY. 
A9 


from the COUNTRYSSYS file. The device must be previously prepared for code page 
switching with the appropriate DEVICE= directive in the CONFIG.SYS file and 
NLSFUNC and MODE CP PREPARE commands (placed in the AUTOEXEC.BAT file, 


usually). 
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Section IT 


ee 


Example: Force the active code page to be the same as the system’s default code page, that is, 
restore the code page that was active when the system was first booted. 


; get current and 
; default code page 


mov ax,6601h ;: function number 
int 21h : transfer to MS-DOS 
jc error ; jump if function failed 


; set code page 


mov bx, dx ; active = default 

mov ax,6602h ; function number 

int 2ih - transfer to MS-DOS 

jc error ; jump if function failed 


ee 


Int 21H [3.3] 
Function 67H (103) 
Set handle count 


a 


Sets the maximum number of files and devices that may be opened simultaneously using handles by the 
current process. 


Oe 


Call with: AH = 67H 

BX = number of desired handles 
a 
Returns: If function successful 


Carry flag = clear 


If function unsuccessful 
Carry flag = set 
AX = error code 


Notes: ® This function call controls the size of the table that relates handle numbers for 
the current process to MS-DOS'’s internal, global table for all of the open files and 
devices in the system. The default table is located in the reserved area of the 
process’s PSP and is large enough for 20 handles. 


™ The function fails if the requested number of handles is greater than 20 and there 
is not sufficient free memory in the system to allocate a new block to hold the 
enlarged table. 
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™ If the number of handles requested is larger than the available entries in the 
system’s global table for file and device handles (controlled by the FILES entry in 
CONFIG.SYS), no error is returned. However, a subsequent attempt to open a file or 
device, or create a new file, will fail if all the entries in the system’s global file table 
are in use, even if the requesting process has not used up all its own handles. 


Example: Set the maximum handle count for the current process to thirty, so that the process can 
have as many as 30 files or devices opened simultaneously. (Five of the handles are 
already assigned to the standard devices when the process starts up.) Note that a 
FILES=30 (or greater value) entry in the CONFIG.SYS file would also be required for the 
process to successfully open 30 files or devices. 


mov ah,67h ; function number 

mov bx, 30 ; maximum number of handles 
int 21h ; transfer to MS-DOS 

jc error ; jump if function failed 


ee 
Int 21H [3.3] 


Function 68H (104) 
Commit file 


Forces all data in MS-DOS’s internal buffers associated with a specified handle to be physically written to 
the device. If the handle refers to a file, and the file has been modified, the time and date stamp and file 
size in the file’s directory entry are updated. 


Ss = 


Call with: AH = 68H 
BX = handle 


Returns: If function successful 
Carry flag =clear 
If function unsuccessful 
Carry flag = set 
AX = error code 


Notes: ® The effect of this function is equivalent to closing and reopening a file, or to 
duplicating a handle for the file with Int 21H Function 45H and then closing the 
duplicate. However, this function has the advantage that it will not fail due to lack of 
handles, and the application does not risk losing control of the file in multitasking or 
network environments. 
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™ If this function is requested for a handle associated with a character device, a success 
flag is returned, but there is no other effect. 


NN 

Example: Assume that the file MYFILE.DAT has been previously opened and that the handle for 
that file is stored in the variable fhandle. Call the Commit File function to ensure that 
any data in MS-DOS’s internal buffers associated with the handle is written out to disk 
and that the directory and file allocation table are up to date. 


fname db "MYFILE.DAT',O ; ASCIIZ filename 
fhandle dw ? : file handle 
aay ah,68h ; function number 
mov bx, fhandle ; file handle 
int 21h > transfer to MS-DOS 
jc error ; jump if commit failed 
A 2 
Int 21H 
Function 69H (105) 
Reserved 
eS 
A 
Int 21H 
Function 6AH (106) 
Reserved 
en a 
a 
Int 21H 
Function 6BH (107) 


Reserved 
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a 
Int 21H [4.0] 


Function 6CH (108) 
Extended open file 
———— eee 


Given an ASCIIZ pathname, opens, creates or replaces a file in the designated or default directory on the 
designated or default disk drive. Returns a handle that can be used by the program for subsequent access 
to the file. 


i se 


Call with: AH = 6CH 


AL = 00H 

BX = open mode 
Bit(s) Significance 
0-2 access type 


000 = read-only 
001 = write-only 
010 = read/write 
3 reserved (0) 
4—6 sharing mode 
000 = compatibility 
OO1 = deny read/write (deny all) 
010 = deny write 
O11 = deny read 
100 = deny none 
7 inheritance 
O = child process inherits handle 
1 = child does not inherit handle 
8-12 reserved (Q) 
13 critical error handling 
O = execute Int 24H 
1 = return error to process 
14 write-through 
O = writes may be buffered and deferred 
1 = physical write at request time 
15 reserved (0) 
CX = file attribute (bits may be combined; ignored if open) 
Bit(s) Significance (if set) 
0 read-only 
1 hidden 
2 system 
3 volume label 
4 reserved (0) 
5 archive 
6-15 reserved (0) 
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DX = open flag 

Bits Significance 

0-3 action if file exists 
0000 = fail 
0001 = open file 
0010 = replace file 

4-7 action if file doesn’t exist 
0000 = fail 
0001 = create file 

8-15 reserved (0) 


DS:SI = segment:offset of ASCIIZ pathname 
ee 
Returns: If function successful 

Carry flag =clear 

AX = handle 

CX = action taken 


1 = file existed and was opened 
2 = file did not exist and was created 
3 = file existed and was replaced 

If function failed 

Carry flag =set 

AX = error code 


I 
Notes: ™® The function fails if: 


— any element of the pathname does not exist. 

— the file is being created in the root directory and the root directory is full. 

— the file is being created and a file with the same name and the read-only attribute 
already exists in the specified directory. 

— the program is running on a network and the user running the program has in- 
sufficient access rights. 

® A file is usually given a normal (0) attribute when it is created. The file’s attribute 
can subsequently be modified with Int 21H Function 43H. 


™ This function combines the capabilities of Int 21H Functions 3CH, 3DH, and 5BH. It 
was added to MS-DOS for compatibility with the DosOpen function of OS/2. 


a i SSS SSS 
Example: Create the file MY FILE.DAT, if it does not already exist, in directory \MYDIR on drive C, 


and save the handle for subsequent access to the file. 


fname db "C:\MYDIR\MYFILE.DAT' ,O 


fhandle dw ? 


(continued) 
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mov ax,6c00h ; function number 


mov bx,4042h ; read/write, deny none, 
; write-through mode 

xor CX,CX ; normal attribute 

mov dx,0010h ; create if doesn't exist, 
; fail if exists 

mov si,seg fname ; address of pathname 

mov ds,si 

mov si,offset fname 

int 21h ; transfer to MS-DOS 

je error ; jump if open failed 

mov fhandle,ax ; save file handle 


———————— 
Int 22H [1.0] 


Terminate handler address 


The machine interrupt vector for Int 22H (memory locations 0000:0088H through 0000:008BH) contains 
the address of the routine that receives control when the currently executing program terminates via Int 
20H, Int 27H, or Int 21H Functions 00H, 31H, or 4CH. The address in this vector is also copied into offsets 
OAH through ODH of the program segment prefix (PSP) when a program is loaded but before it begins 
executing, and is restored from the PSP (in case it was modified by the application) as part of MS-DOS’s 
termination handling. 


This interrupt should never be issued directly. 


——————— 
Int 23H [1.0] 


Ctrl-C handler address 


The machine interrupt vector for Int 23H (memory locations 0000:008CH though 0000:008FH) contains 
the address of the routine which receives control when a Ctrl-C is detected during any character I/O 
function and, if the Break flag is ON, during most other MS-DOS function calls. The address in this vector 
is also copied into locations 0OEH through 11H of the program segment prefix (PSP) when a program is 
loaded but before it begins executing, and is restored from the PSP (in case it was modified by the appli- 
cation) as part of MS-DOS’s termination handling. 


This interrupt should never be issued directly. 


Notes: " The initialization code for an application can use Int 21H Function 25H to reset the 
Interrupt 23H vector to point to its own routine for Ctrl-C handling. In this way, the 
program can avoid being terminated unexpectedly as the result of the user’s entry of 
a Ctrl-C or Ctrl-Break. 
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M® When a Ctrl-C is detected and the program’s Int 23H handler receives control, all 
registers are set to their values at the point of the original function call. The handler 
can then do any of the following: 


— Seta local flag for later inspection by the application, or take any other appropri- 
ate action, and perform an IRET. All registers must be preserved. The MS-DOS 
function in progress will be restarted from scratch and will proceed to comple- 
tion, control finally returning to the application in the normal manner. 

— Take appropriate action and then perform a RET FAR to give control back to MS- 
DOS. The state of the carry flag is used by MS-DOS to determine what action to 
take. If the carry flag is set, the application will be terminated, if the carry flag is 
clear, the application will continue in the normal manner. 

~ Retain control by transferring to an error-handling routine within the application 
and then resume execution or take other appropriate action, never performing a 
RET FAR or IRET to end the interrupt-handling sequence. This option will cause 
no harm to the system. 


™ Any MS-DOS function call may be used within the body of an Int 23H handler. 


Example: See Chapter 5. 


en 


Int 24H [1.0] 
Critical-error handler address 


a 


The machine interrupt vector for Int 24H (memory locations 0000:0090H through 0000:0093H) contains 
the address of the routine that receives control when a critical error (usually a hardware error) is 
detected. This address is also copied into locations 12H through 15H of the program segment prefix (PSP) 
when a program is loaded but before it begins executing, and is restored from the PSP (in case it was 
modified by the application) as part of MS-DOS'’s termination handling. 


This interrupt should never be issued directly. 


Notes: = Onentry to the critical-error interrupt handler, bit 7 of register AH is clear (0) if the 
error was a disk I/O error; otherwise, it is set (1). BP:SI contains the address of a 
device-driver header from which additional information can be obtained. Interrupts 
are disabled. The registers will be set up for a retry operation, and an error code will 
be in the lower half of the DI register, with the upper half undefined. 

The lower byte of DI contains: 


00H write-protect error 

01H unknown unit 

02H drive not ready 

03H unknown command 

04H data error (CRC) 

05H bad request structure length 
06H seek error 

07H unknown media type 

08H sector not found 
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09H printer out of paper 


OAH write fault 

OBH read fault 

OCH general failure 

ODH reserved 

OEH reserved 

OFH invalid disk change (MS-DOS version 3 only) 


Note that these are the same error codes returned by the device driver in the request 
header. Also, upon entry, the stack is set up as shown in Figure 8-8, page 149. 

When a disk I/O error occurs, MS-DOS automatically retries the operation before 
issuing a critical-error Int 24H. The number of retries varies in different versions of 
MS-DOS, but is typically in the range three to five. 

Int 24H handlers must preserve the SS, SP, DS, ES, BX, CX, and DX registers. Only Int 
21H Functions 01H—OCH and 59H can be used by an Int 24H handler: other function 
calls will destroy the MS-DOS stack and its ability to retry or ignore an error. 

When the Int 24H handler issues an IRET, it should return an action code in AL that 
will be interpreted by DOS as follows: 


0 ignore the error 

1 retry the operation 

2 terminate the program 

3 [3.0+] fail the function call in progress 


If the Int 24H handler returns control directly to the application program rather than 
to MS-DOS, it must restore the program’s registers, removing all but the last three 
words from the stack, and issue an IRET. Control returns to the instruction immedi- 
ately following the function call that caused the error. This option leaves MS-DOS 

in an unstable state until a call to an Int 21H function higher than Function OCH 

is made. 


a 


Example: 


See Chapter 8. 


ee 
Int 25H 
Absolute disk read 

a 


Provides a direct linkage to the MS-DOS BIOS module to read data from a logical disk sector into memory. © 


55 i 


Call with: 


482 


[1.0] 


For access to partitions <= 32 MB 

AL = drive number (0 = A, 1 = B, etc) 
CX = number of sectors to read 

DX = starting sector number 

DS:BX = segment:offset of buffer 


For access to partitions > 32 MB (MS-DOS 4.0 and later) 


AL = drive number (0 = A, 1 = B, etc) 

CX =—] 

DS:BX = segment:offset of parameter block (see Notes) 
Section IT 


a 


Returns: If function successful 
Carry flag =clear 


If function unsuccessful 
Carry flag = set 
AX = error code (see Notes) 


a 


Notes: # All registers except the segment registers may be destroyed. 


® When this function returns, the CPU flags originally pushed on the stack by the INT 
25H instruction are stil] on the stack. The stack must be cleared by a POPF or ADD 
SP.2 to prevent uncontrolled stack growth and to make accessible any other values 
that were pushed on the stack before the call to INT 25H. 


™ Logical sector numbers are obtained by numbering each disk sector sequentially 
. from cylinder 0, head 0, sector 1, and continuing until the last sector on the disk is 
counted. The head number is incremented before the track number. Logically adja- 
cent sectors may not be physically adjacent, due to interleaving that occurs at the 
device-adapter level for some disk types. 


™ The error code is interpreted as follows: The lower byte (AL) is the same error code 


that is returned in the lower byte of DI when an Int 24H is issued. The upper byte 
(AH) contains: 


01H if bad command 

02H if bad address mark 

04H if requested sector not found 

08H if direct memory access (DMA) failure 
10H if data error (bad CRC) 

20H if controller failed 

40H if seek operation failed 

80H if attachment failed to respond 


= [4.0+] When accessing partitions larger than 32 MB under MS-DOS version 4, this 
function uses a parameter block. with the following format: 
Bytes Description 
OOH-03H 32-bit sector number 
04H-05SH number of sectors to read 
06H-07H offset of buffer 
O8H-09H segment of buffer 


ne 


Example: Read logical sector 1 of drive A into the memory area named buff. (On most MS-DOS 
floppy disks, this sector contains the beginning of the file allocation table.) 


buf f db 512 dup (?) > receives data from disk 


(continued) 
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mov al,0 ; drive A 


mov cx,l ; number of sectors 

mov dx,1 ; beginning sector number 
mov bx, seg buff ; buffer address 

mov ds ,bx 

mov bx,offset buff 

int 25h ; request disk read 

jc error ; jump if read failed 

add sp,2 ; clear stack 


SS SSeS ese 


Int 26H 


[1.0] 


Absolute disk write 


SS I ea I I I ED 


Provides a direct linkage to the MS-DOS BIOS module to write data from memory to a logical disk sector. 


i es 


Call with: 


Returns: 


For access to partitions <= 32 MB 


AL = drive number (0 = A, 1 = B, etc) 

CX = number of sectors to write 

DX = starting sector number 

DS:BX = segment:offset of buffer 

For access to partitions > 32 MB (MS-DOS 4.0 and later) 

AL = drive number (0 = A, 1 = B, etc) 

CX =-] 

DS:BX = segment:offset of parameter block (see Notes) 


If function successful 

Carry flag =clear 

If function unsuccessful 

Carry flag = set 

AX = error code (see Notes) 


COO SSS 


Notes: 


= All registers except the segment registers may be destroyed. 


™ When this function returns, the CPU flags originally pushed onto the stack by the 
INT 26H instruction are still on the stack. The stack must be cleared by a POPF or 
ADD SP,2 to prevent uncontrolled stack growth and to make accessible any other 
values that were pushed on the stack before the call to INT 26H. 


= Logical sector numbers are obtained by numbering each disk sector sequentially 
from cylinder 0, head 0, sector 1, and continuing until the last sector on the disk is 
counted. The head number is incremented before the track number. Logically adja- 
cent sectors may not be physically adjacent, due to interleaving that occurs at the 
device-adapter level for some disk types. | 
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™ The error code is interpreted as follows: The lower byte (AL) is the same error code 
that is returned in the lower byte of DI when an Int 24H is issued. The upper byte 
(AH) contains: | 


01H 
02H 
03H 
04H 
08H 
10H 
20H 
40H 
80H 


if bad command 

if bad address mark 

if write-protect fault 

if requested sector not found 

if direct memory access (DMA) failure 
if data error (bad CRC) 

if controller failed 

if seek operation failed 

if attachment failed to respond 


™ (4.0+] When accessing partitions larger than 32 MB under MS-DOS version 4, this 
function uses a parameter block with the following format: 


Bytes 

OOH—03H 
04H-05H 
06H-07H 
0O8H-—09H 


Description 

32-bit sector number 
number of sectors to read 
offset of buffer 

segment of buffer 


Example: 


Write the contents of the memory area named buff into logical sector 3 of drive C. 
Warning: Verbatim use of the following code could damage the file system on your 
fixed disk. There is, unfortunately, no way to provide a really safe example of this 


function. 


buff db 


mov 
mov 
mov 
mov 
mov 
mov 
int 
je 

add 


512 dup (?) ; contains data for write 
al,2 ; drive C 

cx,1 ; number of sectors 

dx,3 ; beginning sector number 
bx,seg buff ; buffer address 

ds,bx 

bx, offset buff 

26h ; request disk write 
error ; jump if write failed 
sp,2 ; clear stack 
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ee 
Int 27H [1.0] 


Terminate and stay resident 
a 


Terminates execution of the currently executing program, but reserves part or all of its memory so that it 
will not be overlaid by the next transient program to be loaded. MS-DOS then takes the following actions: 


= File buffers are flushed and any open handles for files or devices owned by the 
process are closed. 


= The termination handler vector (Int 22H) is restored from PSP:000AH. 

@ The Ctrl-C handler vector (Int 23H) is restored from PSP:O00EH. 

m (2.0+) The critical-error handler vector (Int 24H) is restored from PSP:0012H. 
= Control is transferred to the termination handler. 


If the program is returning to COMMAND.COM, control transfers to the resident portion and the transient 
portion is reloaded if necessary. If a batch file is in progress, the next line of the file is fetched and inter- 
preted; otherwise a prompt is issued for the next user command. 


a 


Call with: Dx = offset of the last byte plus one (relative to the program segment prefix) 
of program to be protected 
CS = segment of program segment prefix 


as 8 les 
Returns: Nothing 


OO OO EE 


Notes: ™ This function call is typically used to allow user-written utilities, drivers, or interrupt 
handlers to be loaded as ordinary .COM or .EXE programs, then remain resident. 
Subsequent entrance to the code is via a hardware or software interrupt. 


= This function attempts to set the initial memory allocation block to the length in 
bytes specified in register DX. If other memory blocks have been requested by the 
application via Int 21H Function 48H, they will not be released by this function. 


@ Other methods of performing a final exit are: 


Int 20H 

Int 21H Function 00H 
Int 21H Function 31H 
Int 21H Function 4CH 


@ This function should not be called by .EXE programs that are loaded at the high end 
of the transient program area (i.e., linked with the /HIGH switch), because doing so 
reserves the memory normally used by the transient part of COMMAND.COM. If 
COMMAND.COM cannot be reloaded, the system will fail. 

= This function does not work correctly when DX contains values in the range 
OFFF1H-OFFFFH. In this case, MS-DOS discards the high bit of the value in DX, 
resulting in the reservation of 32 KB less memory than was requested by the 
program. 


@ [2.0+] Int 21H Function 31H should be used in preference to this function, because it 
supports return codes, allows larger amounts of memory to be reserved, and does 
not require CS to contain the segment of the program segment prefix. 
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® (3.0+] If the program is running on a network, it should remove all locks it has 
placed on file regions before terminating. 


Example: Terminate and stay resident, reserving enough memory to contain the entire program. 


mov dx,offset pend ; DX = bytes to reserve 
int 27h : terminate, stay resident 

pend equ $ ; offset, end of program 
end 
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Provides a general-purpose avenue of communication with another process or with MS-DOS extensions, 
such as the print spooler, ASSIGN, SHARE, and APPEND. The multiplex number in register AH specifies 
the process or extension being communicated with. The range 0OH-BFH is reserved for MS-DOS; appli- 
cations may use the range COH—FFH. 


5 


[3.0] 
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Submits a file to the print spooler, removes a file from the print spooler’s queue of pending files, or ob- 
tains the status of the printer. The print spooler, which is contained in the file PRINT.COM, was first 
added to MS-DOS in version 2.0, but the application program interface to the spooler was not docu- 
mented until MS-DOS version 3. 


Call with: AH = 01H 

AL = subfunction 
OOH = Get Installed State 
01H = Submit File to be Printed 
02H = Remove File from Print Queue 
03H = Cancel All Files in Queue 
04H = Hold Print Jobs for Status Read 
O5H = Release Hold 

DS:DX = segment:offset of packet (Subfunction 01H) 
segment:offset of ASCIIZ pathname (Subfunction 02H) 
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Returns: 


N otes: 


If function successful 
Carry flag = clear 


and, if called with AL = 00H 


AL = print spooler state 
OOH if not installed, ok to install 
01H if not installed, not ok to install 


FFH if installed 


or, if called with AL = 04H 
DX = error count 
DS:SI = segment:offset of print queue file list 


If function unsuccessful 
Carry flag =set 
AX = error code 


m= The packet passed to Subfunction 01H consists of five bytes. The first byte contains 
the /evel, which should be 00H for current versions of MS-DOS. The following four 
bytes contain the segment:offset of an ASCIIZ pathname, which may not include 
wildcard characters. If the specified file exists, it is added to the print queue. 

mw The + and? wildcard characters may be included in a pathname passed to Subfunc- 


tion 02H, making it possible to delete multiple files from the print queue with one 
call. 


ge The address returned by Subfunction 04H points to a list of 64-byte entries, each 


containing an ASCIIZ pathname. The first pathname in the list is the file currently 
being printed. The last entry in the list is a null string (a single 00H byte). 


Int 2FH 


[3.2] 


Function 02H 


ASSIGN 


Returns a code indicating whether the resident portion of the ASSIGN utility has been loaded. 


Call with: 


Returns: 


AH = 02H 
AL = subfunction 
OOH = Get Installed State 


If function successful 
Carry flag =clear 


AL = ASSIGN installed status 
OOH if not installed, ok to install 
01H if not installed, not ok to install 
FFH if installed 


If function unsuccessful 
Carry flag =set 
AX = error code 
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Int 2FH [3.2] 
Function 10H (16) 
SHARE 


Returns a code indicating whether the SHARE.EXE file-sharing module has been loaded. 


Call with: AH = 10H 
AL = subfunction 
OOH = Get Installed State 


Returns: If function successful 
Carry flag =clear 
AL = SHARE installed status 
OOH if not installed, ok to install 
01H if not installed, not ok to install 


FFH if installed 


If function unsuccessful 
Carry flag =set 


AX = error code 
Int 2FH [3.3] 
Function B7H (183) | 


APPEND 


Allows an application to test whether APPEND has been installed. If APPEND is resident, returns the 
APPEND version, state, and the path used to search for data files. 


Call with: AH = B7H 
| AL = subfunction 
OOH = Get Installed State 
02H = Get Append Version (4.0) 
04H = Get Append Path Pointer (4.0) 
06H = Get Append Function State (4.0) 
07H = Set Append Function State (4.0) 
11H = Set Return Found Name State (4.0, see Note) 


BX = APPEND state Gif AL = 07H) 
Bit(s) Significance (if set) 
0 APPEND enabled 
1-12 Reserved (0) 
13 /PATH switch active 
14 /E switch active 
15 /X switch active 
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Returns: If function successful 
Carry flag =clear 


and, if called with AL = 00H 


AL = APPEND installed status 
OOH if not installed, ok to install 
01H if not installed, not ok to install 


FFH if installed 


or, if called with AL = 02H (MS-DOS 4.0) 

AX = FFFFH if MS-DOS 4.0 APPEND 

or, if called with AL = 04H (MS-DOS 4.0) 

ES:DI = segment:offset of active APPEND path 
or, if called with AL = 06H (MS-DOS 4.0) 

BX = APPEND state (see above) 

If function unsuccessful 

Carry flag = set 

AX = error code 


Note: = Ifthe Return Found Name State is set with Subfunction 11H, the fully qualified file- 
name is returned to the next application to call Int 21H Function 3DH, 43H, or 6CH. 
The name is placed at the same address as the ASCIIZ parameter string for the Int 
21H function, so the application must be sure to provide a buffer of adequate size. 
The Return Found Name State is reset after APPEND processes one Int 21H 
function call. 
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Notes to the Reader 


In the headers for ROM BIOS video driver Cnt 10H) function calls, the 
following icons are used: 


[MDA] Monochrome Display Adapter 

[CGA] Color/Graphics Adapter 

[PCjr] PCjr system board video controller 

[EGA] Enhanced Graphics Adapter 

[MCGA] Multi-Color Graphics Array (PS/2 Models 25 & 30) 
[VGA] Video Graphics Array (PS/2 Models 50 and above) 


In the remainder of this section, the following icons are used: 


[PC] Original IBM PC, PC/XT, and PCjr, unless otherwise noted. 

[AT] PC/AT and PC/XT-286, unless otherwise noted. 

[PS/2] All PS/2 models Gincluding Models 25 and 30), unless other- 
wise noted. 


ROM BIOS functions that are unique to the PC Convertible have been 
omitted. 


Some functions are supported only in very late revisions of a particular 
machine’s ROM BIOS (such as Int 1AH Functions 00H and 01H on the 
PC/XT). In general, such functions are not given an icon for that machine 
since a program could not safely assume that they were available based on 
the machine ID byte(s). 


Summary of ROM BIOS and Mouse Function Calls 


Int Function Subfunction Name 

10H Video Driver 

10H 00H Set Video Mode 

10H 01H Set Cursor Type 

10H 02H Set Cursor Position 

10H 03H Get Cursor Position 

10H 04H Get Light Pen Position 

10H 05H Set Display Page 

10H 06H Initialize or Scroll Window Up 

10H 07H Initialize or Scroll Window Down 

10H 08H Read Character and Attribute at Cursor 
10H 09H Write Character and Attribute at Cursor 
10H OAH(O) Write Character at Cursor 

10H OBH (11) Set Palette, Background, or Border 


(continued) 
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Summary of ROM BIOS and Mouse Function Calls continued 


Int 


10H 
10H 
10H 
10H 
10H 
10H 
10H 
10H 
10H 
10H 
10H 
10H 
10H 
10H 
10H 
10H 
10H 
10H 
10H 
10H 
10H 
10H 
10H 
10H 
10H 


10H 


10H 


10H 
10H 
10H 
10H 
10H 
10H 
10H 
10H 
10H 
10H 
10H 
10H 
10H 


Function 


OCH (12) 
ODH (13) 
OEH (14) 
OFH (15) 
10H (16) 
10H (16) 
10H (16) 
10H (16) 
10H (16) 
10H (16) 
10H (16) 
10H (16) 
10H (16) 
10H (16) 
10H (16) 
10H (16) 
10H (16) 
10H (16) 
11H (17) 
11H (17) 
11H (17) 
11H (17) 
11H (17) 
11H (17) 
11H (17) 


11H (17) 
11H (17) 


11H (17) 
11H (17) 
11H (17) 
11H (17) 
11H (17) 
11H (17) 
12H (18) 
12H (18) 
12H (18) 
12H (18) 
12H (18) 
12H (18) 
12H (18) 


Subfunction 


00H 
01H 
02H 
03H 
07H 
08H 
09H 
10H (16) 
12H (18) 
13H (19) 
15H (21) 
17H (23) 
1AH (26) 
1BH (27) 
00H 
01H 
02H 
03H 
04H 
10H (16) 
11H (17) 


12H (18) 
14H (20) 


20H (32) 
21H (33) 
22H (34) 
23H (35) 
24H (36) 
30H (48) 
10H (16) 
20H (32) 
30H (48) 
31H (49) 
32H (50) 
33H (51) 
34H (52) 


Name 


Write Graphics Pixel 

Read Graphics Pixel 

Write Character in Teletype Mode 

Get Video Mode 

Set Palette Register 

Set Border Color 

Set Palette and Border 

Toggle Blink/Intensity Bit 

Get Palette Register 

Get Border Color 

Get Palette and Border 

Set Color Kegister 

Set Block of Color Registers 

Set Color Page State 

Get Color Register 

Get Block of Color Registers 

Get Color Page State 

Set Gray-Scale Values 

Load User Font 

Load ROM 8-by-14 Font 

Load ROM 8-by-8 Font 

Set Block Specifier 

Load ROM 8-by-16 Font 

Load User Font, Reprogram Controller 

Load ROM 8-by-14 Font, Reprogram 
Controller 

Load ROM 8-by-8 Font, Reprogram 
Controller 

Load ROM 8-by-16 Font, Reprogram 
Controller 

Set Int 1FH Pointer 

Set Int 43H for User’s Font 

Set Int 43H for ROM 8-by-14 Font 

Set Int 43H for ROM 8-by-8 Font 

Set Int 43H for Rom 8-by-16 Font 

Get Font Information 

Get Configuration Information 

Select Alternate PrintScreen 

Set Scan Lines 

Enable/Disable Palette Loading 

Enable/Disable Video 

Enable/Disable Gray-Scale Summing 

Enable/Disable Cursor Emulation 


(continued) 
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Summary of ROM BIOS and Mouse Function Calls continued 


Int Function 
10H 12H (18) 
10H 12H (18) 
10H 13H (19) 
10H 1AH (26) 
10H 1BH (27) 
10H 1CH (28) 
11H 

12H 

13H 

13H 00H 

13H 01H 

13H 02H 

13H 03H 

13H 04H 

13H 05H 

13H 06H 

13H 07H 

13H 08H 

13H 09H 

13H OAH (10) 
13H OBH (11) 
13H OCH (12) 
13H ODH (13) 
13H OEH (14) 
13H OFH (15) 
13H 10H (16) 
13H 11H (17) 
13H 12H (18) 
13H 13H (19) 
13H 14H (20) 
13H 15H (21) 
13H 16H (22) 
13H 17H (23) 
13H 18H (24) 
13H 19H (25) 
13H 1AH (26) 
14H 

14H 00H 

14H 01H 
Section IIT 


35H (53) 
36H (54) 


Subfunction Name 


Switch Active Display 

Enable/Disable Screen Refresh 

Write String in Teletype Mode 

Get or Set Display Combination Code 
Get Functionality/State Information 
Save or Restore Video State 


Get Equipment Configuration 
Get Conventional Memory Size 


Disk Driver 

Reset Disk System 

Get Disk System Status 
Read Sector 

Write Sector 

Verify Sector 

Format Track 

Format Bad Track 

Format Drive 

Get Drive Parameters 
Initialize Fixed Disk Characteristics 
Read Sector Long 

Write Sector Long 

Seek 

Reset Fixed Disk System 
Read Sector Buffer 

Write Sector Buffer 

Get Drive Status 
Recalibrate Drive 
Controller RAM Diagnostic 
Controller Drive Diagnostic 
Controller Internal Diagnostic 
Get Disk Type 

Get Disk Change Status 

Set Disk Type 

Set Media Type for Format 
Park Heads 

Format ESDI Drive 


Serial Communications Port Driver 


Initialize Communications Port 
Write Character to Communications Port 


(continued) 


Summary of ROM BIOS and Mouse Function Calls continued 


Int 
14H 


14H 
14H 


14H 


15H 
15H 
15H 
15H 
15H 
15H 
15H 
15H 
15H 
15H 
15H 
15H 
15H 
15H 
15H 
15H 
15H 
15H 
15H 
15H 
15H 
15H 
15H 


15H 
15H 
15H 
15H 
15H 
15H 
15H 
15H 
15H 
15H 


Function 


02H 


03H 
04H 


05H 


00H 

01H 

02H 

03H 

OFH (15) 
21H (33) 
21H (33) 
4FH (79) 
80H (128) 
81H (129) 
82H (130) 
83H (131) 
84H (132) 
85H (133) 
86H (134) 
87H (135) 
88H (136) 
89H (137) 
90H (144) 
91H (145) 
COH (192) 
C1H (193) 


C2H (194) 
C2H (194) 
C2H (194) 
C2H (194) 
C2H (194) 
C2H (194) 
C2H (194) 
C2H (194) 
C3H (195) 
C4H (196) 


Subfunction 


00H 
01H 


00H 
01H 
02H 
03H 
04H 
05H 
06H 
07H 


Name 


Read Character from Communications 
Port 

Get Communications Port Status 

Extended Initialize Communications 
Port 

Extended Communications Port Control 


I/O Subsystem Extensions 

Turn On Cassette Motor 

Turn Off Cassette Motor 

Read Cassette 

Write Cassette 

Format ESDI Drive Periodic Interrupt 

Read POST Error Log 

Write POST Error Log 

Keyboard Intercept 

Device Open 

Device Close 

Process Termination 

Event Wait 

Read Joystick 

SysReq Key 

Delay 

Move Extended Memory Block 

Get Extended Memory Size 

Enter Protected Mode 

Device Wait 

Device Post 

Get System Environment 

Get Address of Extended BIOS Data 
Area 

Enable/Disable Pointing Device 

Reset Pointing Device 

Set Sample Rate 

Set Resolution 

Get Pointing Device Type 

Initialize Pointing Device Interface 

Set Scaling or Get Status 

Set Pointing Device Handler Address 

Set Watchdog Time-Out 

Programmable Option Select 


(continued) 
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Summary of ROM BIOS and Mouse Function Calls continued 


Int Function Subfunction Name 

16H Keyboard Driver 

16H 00H Read Character from Keyboard 

16H 01H Get Keyboard Status 

16H 02H Get Keyboard Flags 

16H 03H Set Repeat Rate 

16H 04H Set Keyclick 

16H 05H Push Character and Scan Code 

16H 10H (16) Read Character from Enhanced 
Keyboard 

16H 11H (17) Get Enhanced Keyboard Status 

16H 12H (18) Get Enhanced Keyboard Flags 

17H Parallel Port Printer Driver 

17H 00H Write Character to Printer 

17H 01H Initialize Printer Port 

17H 02H Get Printer Status 

18H ROM BASIC 

19H Reboot System 

1AH Real-time (CMOS) Clock Driver 

1AH 0OH Get Tick Count 

1AH 01H Set Tick Count 

1AH 02H Get Time 

1AH 03H Set Time 

1AH 04H | Get Date 

1AH 05H Set Date 

1AH 06H Set Alarm 

1AH 07H Reset Alarm 

1AH OAH(10) Get Day Count 

1AH OBH(11) Set Day Count 

1AH 80H (128) Set Sound Source 

33H Microsoft Mouse Driver 

33H OOH Reset Mouse and Get Status 

33H 01H Show Mouse Pointer 

33H 02H Hide Mouse Pointer 

33H 03H Get Mouse Position and Button Status 

33H 04H Set Mouse Pointer Position 

33H 05H Get Button Press Information 

33H 06H Get Button Release Information 

33H 07H Set Horizontal Limits for Pointer 

33H 08H Set Vertical Limits for Pointer 

33H 09H Set Graphics Pointer Shape 

(continued) 
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Summary of ROM BIOS and Mouse Function Calls continued 


Int 


33H 
33H 
33H 
33H 
33H 
33H 
33H 
33H 
33H 


33H 
33H 
33H 
33H 
33H 


33H 
33H 
33H 
33H 
33H 
33H 
33H 
33H 
33H 
33H 
33H 


Function 


OAH (10) 
OBH (11) 
OCH (12) 
ODH (13) 
OEH (14) 
OFH (15) 
10H (16) 
13H (19) 
14H (20) 


15H (21) 
16H (22) 
17H (23) 
18H (24) 
19H (25) 


1AH (26) 
1BH (27) 
1CH (28) 
1DH (29) 
1EH (30) 
1FH (31) 
20H (32) 
21H G3) 
22H (34) 
23H (35) 
24H (36) 


Subfunction Name 


Set Text Pointer Type 

Read Mouse Motion Counters 

Set User-defined Mouse Event Handler 

Turn On Light Pen Emulation 

Turn Off Light Pen Emulation 

Set Mickeys to Pixels Ratio 

Set Mouse Pointer Exclusion Area 

Set Double Speed Threshold 

Swap User-defined Mouse Event 
Handlers 

Get Mouse Save State Buffer Size 

Save Mouse Driver State 

Restore Mouse Driver State 

Set Alternate Mouse Event Handler 

Get Address of Alternate Mouse Event 
Handler 

Set Mouse Sensitivity 

Get Mouse Sensitivity 

Set Mouse Interrupt Rate 

Select Pointer Page 

Get Pointer Page 

Disable Mouse Driver 

Enable Mouse Driver 

Reset Mouse Driver 

Set Language for Mouse Driver Messages 

Get Language Number 

Get Mouse Information 
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cl 
Int 10H [MDA] [CGA] [PCjr] [EGA] [MCGA] [VGA] 
Function 00H 


Set video mode 
ee a a ee 


Selects the current video display mode. Also selects the active video controller, if more than one video 
controller is present. 


Call with: AH = 00H 


AL = video mode (see Notes) 


Returns: Nothing 


ee ee eee 
Notes: ™ The video modes applicable to the various IBM machine models and video adapters 


are as follows: 


Cena reeeeee aeSS  e EE 


Text/ 
Mode Resolution Colors graphics MDA CGA PCr EGA MCGA VGA 
OOH  40-by-25 16 text : : ; : A 
color burst off 
O1H  40-by-25 16 text : ; ‘ : : 
02H 80-by-25 16 text * . . . ° 
color burst off 
03H 80-by-25 16 text ° ° . . . 
04H  320-by-200 4 graphics . . . . . 
05H  320-by-200 4 graphics . . . * . 
color burst off 
06H  640-by-200 2 graphics . . . . . 
07H 80-by-25 21 text * * * 
08H 160-by-200 16 graphics . 
09H  320-by-200 16 graphics . 
OAH 640-by-200 4 graphics . 
OBH reserved 
OCH reserved 
ODH  320-by-200 16 graphics . . 
OEH  640-by-200 16 graphics “ * 
OFH  640-by-350 22 graphics . . 
10H 640-by-350 4 graphics 3 
10H 640-by-350 16 graphics 24 . 
11H 640-by-480 2 graphics . . 
12H  640-by-480 16 graphics . 
13H 320-by-200 256 graphics . . 


1 Monochrome monitor only. 

2 Monochrome monitor only. 

3 EGA with 64 KB of RAM. 

4 EGA with 128 KB or more of RAM. 


™ The presence or absence of color burst is only significant when a composite monitor 
is being used. For RGB monitors, there is no functional difference between modes 
OOH and 01H or modes 02H and 03H. On the CGA, two palettes are available in 
mode 04H and one in mode 05H. 
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= On the PC/AT, PCjr, and PS/2, if bit 7 of AL is set, the display buffer is not cleared 
when a new mode is selected. On the PC or PC/XT, this capability is available only 
when an EGA or VGA (which have their own ROM BIOS) is installed. 


Int 10H 
Function 01H 
Set cursor type 


‘[MDA] [CGA] [PCjr] [EGA] [VGA] 


Selects the starting and ending lines for the blinking hardware cursor in text display modes. 


Call with: AH = 01H 
CH bits 0—4 = starting line for cursor 
CL bits 0-4 = ending line for cursor 


Returns: Nothing 


Notes: = In text display modes, the video hardware causes the cursor to blink, and the blink 
cannot be disabled. In graphics modes, the hardware cursor is not available. 


= The default values set by the ROM BIOS are: 


Display Start End 
monochrome mode 07H 11 12 
text modes 0OOH—03H 6 7 


m™ On the EGA, MCGA, and VGA in text modes 00H—03H, the ROM BIOS accepts cur- 
sor start and end values as though the character cell were 8 by 8 and remaps the 
values as appropriate for the true character cell dimensions. This mapping is called 
cursor emulation. 

™ You can turn off the cursor in several ways. On the MDA, CGA, and VGA, setting 
register CH = 20H causes the cursor to disappear. Techniques that involve setting 
illegal starting and ending lines for the current display mode are unreliable. An 
alternative is to position the cursor to a nondisplayable address, such as (%,y)=(0,25). 


a SA EE SS 


Int 10H [MDA] [CGA] [PCjr] [EGA] [MCGA] [VGA] 
Function 02H 
Set cursor position 


Positions the cursor on the display, using text coordinates. 


Call with: AH = 02H 
BH = page 
DH = row (y coordinate) 
DL = column (x coordinate) 
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Returns: Nothing 


Notes: = A separate cursor is maintained for each display page, and each can be set indepen- 
dently with this function regardless of the currently active page. The number of 
available display pages depends on the video adapter and current display mode. See 
Int 10H Function 05H. 


= Text coordinates (%,y)=(0,0) are the upper left corner of the screen. 


= The maximum value for each text coordinate depends on the video adapter and 
current display mode, as follows: 


Mode Maximum x Maximum y 

00H 39 24 

01H 39 24 

02H 79 24 

03H 79 24 

04H 39 24 

05H 39 24 

06H 79 24 

07H 79 24 

08H 19 24 

09H 39 24 

OAH 79 24 

0OBH reserved 

0CH reserved 

ODH 39 24 

0OEH 79 24 

OFH 79 24 

10H 79 24 

11H 79 29 

12H 79 29 

13H 39 24 
SSS nes 
Int 10H [MDA] [CGA] [PCjr] [EGA] [MCGA] [VGA] 
Function 03H 
Get cursor position 


ee 


Obtains the current position of the cursor on the display, in text coordinates. 


Call with: AH = 03H 
BH = page 

Returns: CH = starting line for cursor 
CL = ending line for cursor 
DH = row (y coordinate) 
DL = column (x coordinate) 
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Note: ™ A separate cursor is maintained for each display page, and each can be inspected in- 
dependently with this function regardless of the currently active page. The number 
of available display pages depends on the video adapter and current display mode. 
See Int 10H Function 05H. 


Int 10H [CGA] [PCjr] [EGA] 
Function 04H 
Get light pen position 


Obtains the current status and position of the light pen. 


Call with: AH = 04H 
Returns: AH = 00H if light pen not down/not triggered 
01H if light pen down/triggered 
BX = pixel column (graphics x coordinate) 
CH = pixel row (graphics yy coordinate, modes 04H-06H) 
CX = pixel row (graphics y coordinate, modes ODH-13H) 
DH = character row (text y coordinate) 
DL = character column (text x coordinate) 
Notes: m The range of text and graphics coordinates returned by this function depends on the 


current display mode. 


= On the CGA, the graphics coordinates returned by this function are not continuous. 
The y coordinate is always a multiple of two; the x coordinate is either a multiple of 
four (for 320-by-200 graphics modes) or a multiple of eight (for 640-by-200 graphics 
modes). 

= Careful selection of background and foreground colors is necessary to obtain maxi- 
mum sensitivity from the light pen across the full screen width. 


Int 10H [CGA] [PCjr] [EGA] [MCGA] [VGA] 
Function 05H 
Set display page 


Selects the active display page for the video display. 
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Call with: — For CGA, EGA, MCGA, VGA 

AH = 05H 

AL = page 
O—7 for modes OOH and 01H (CGA, EGA, MCGA, VGA) 
0-3 for modes 02H and 03H (CGA) 
0-7 for modes 02H and 03H (EGA, MCGA, VGA) 
O-7 for mode 07H (EGA, VGA) 
O-7 for mode ODH (EGA, VGA) 
0-3 for mode OEH (EGA, VGA) 
O-1 for mode OFH (EGA, VGA) 
O-1 for mode 10H (EGA, VGA) 


For PCjr only 
AH = 05H 
AL = subfunction 


SOH = read CRT/CPU page registers 

81H = set CPU page register 

82H = set CRT page register 

83H = set both CPU and CRT page registers 
BH = CRT page (Subfunctions 82H and 83H) 
BL = CPU page (Subfunctions 81H and 83H) 


Returns: If CGA, EGA, MCGA, or VGA adapter 
Nothing 
If PCjr and if function called with AL= 80H—83H 
BH = CRT page register 
BL _ = CPU page register 


Notes: ™ Video mode and adapter combinations not listed above support one display page 
(for example, a Monochrome Adapter in mode 7). 


= Switching between pages does not affect their contents. In addition, text can be 
written to any video page with Int 10H Functions 02H, 09H, and OAH, regardless of 
the page currently being displayed. 

| On the PCjr, the CPU page determines the part of the physical memory region 
Q00000H-1FFFFH that will be hardware mapped onto 16 KB of memory beginning 
at segment B800H. The CRT page determines the starting address of the physical 
memory used by the video controller to refresh the display. Smooth animation 
effects can be achieved by manipulation of these registers. Programs that write 
directly to the B800H segment can reach only the first 16 KB of the video refresh 
buffer. Programs requiring direct access to the entire 32 KB buffer in modes 09H and 
OAH can obtain the current CRT page from the ROM BIOS variable PAGDAT at 
0040:008AH. 
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Int 10H [MDA] [CGA] [PCjr] [EGA] [MCGA] [VGA] 
Function 06H 
cna or inion winow up 


Initializes a sated window of the display to ASCII blank characters with a given Jereibune or peeaiee up 
the contents of a window by a specified number of lines. 


Call with: AH = 06H 
AL = number of lines to scroll Gif zero, entire window is blanked) 
BH = attribute to be used for blanked area 
CH = y coordinate, upper left corner of window 
CL = x coordinate, upper left corner of window 
DH = y coordinate, lower right corner of window 
DL = x coordinate, lower right corner of window 


Returns: Nothing 


Notes: ™ In video modes that support multiple pages, this function affects only the page 
currently being displayed. 
m™ If AL contains a value other than 00H, the area within the specified window is 
scrolled up by the requested number of lines. Text that is scrolled beyond the top of 
the window is lost. The new lines that appear at the bottom of the window are filled 
with ASCII blanks carrying the attribute specified by register BH. 


® ‘To scroll down the contents of a window, see Int 10H Function 07H. 


Int 10H [MDA] [CGA] [PCjr] [EGA] [MCGA] [VGA] 
Function 07H 


Initialize or scroll window down 


Initializes a specified window of the display to ASCII blank characters with a given attribute, or scrolls 
down the contents of a window by a specified number of lines. 


Call with: AH = 07H 
AL = number of lines to scroll Cif zero, entire window is blanked) 
BH = attribute to be used for blanked area 
CH = y coordinate, upper left corner of window 
CL = x coordinate, upper left corner of window 
DH = y coordinate, lower right corner of window 
DL = x coordinate, lower right corner of window 


Returns: Nothing 
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Notes: ™ In video modes that support multiple pages, this function affects only the page 
currently being displayed. 
= If AL contains a value other than 00H, the area within the specified window is 
scrolled down by the requested number of lines. Text that is scrolled beyond the 
bottom of the window is lost. The new lines that appear at the top of the window 
are filled with ASCII blanks carrying the attribute specified by register BH. 


= To scroll up the contents of a window, see Int 10H Function 06H. 


Int 10H [MDA] [CGA] [PCG r] [EGA] [MCGA] [VGA] 
Function 08H 
Read character and attribute at cursor 


Obtains the ASCII character and its attribute at the current cursor position for the specified display page. 


Call with: AH = 08H 
BH = page 
Returns: AH = attribute 
AL = character 
Note: = In video modes that support multiple pages, characters and their attributes may be 


read from any page, regardless of the page currently being displayed. 


Int 10H [MDA] [CGA] [PCj r] [EGA] [MCGA] [VGA] 
Function 09H 
Write character and attribute at cursor 


Writes an ASCII character and its attribute to the display at the current cursor position. 


Callwith: AH = 09H 
AL = character 
BH = page 
BL = attribute (text modes) or color (graphics modes) 
CX = count of characters to write (replication factor) 


a a ee ee ee ee 
Returns: Nothing 
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OO 


Notes: = In graphics modes, the replication factor in CX produces a valid result only for the 
current row. If more characters are written than there are remaining columns in the 
current row, the result is unpredictable. 

= All values of AL result in some sort of display; control characters, including bell, 
backspace, carriage return, and line feed, are not recognized as special characters 
and do not affect the cursor position. 

= After a character is written, the cursor must be moved explicitly with Int 10H Func- 
tion 02H to the next position. . 

= To write a character without changing the attribute at the current cursor position, 
use Int 10H Function OAH. 

= If this function is used to write characters in graphics mode and bit 7 of BL is set (1), 
the character will be exclusive-OR’d (XOR) with the current display contents. This 
feature can be used to write characters and then “erase” them. 

m For the CGA and PCjr in graphics modes 04H—06H, the bit patterns for character 
codes 80H-FFH are obtained from a table whose address is stored in the vector for 
Int 1FH. On the PCjr, the address of the table for character codes OOH—7FH is stored 
in the vector for Int 44H. Alternative character sets may be installed by loading them 
into memory and updating this vector. 

= For the EGA, MCGA, and VGA in graphics modes, the address of the character defini- 
tion table is stored in the vector for Int 43H. See Int 10H Function 11H. 


A 


Int 10H [MDA] [CGA] [PCj r] [EGA] [MCGA] [VGA] 
Function 0AH (10) 
Write character at cursor 


2... 


Writes an ASCII character to the display at the current cursor position. The character receives the 
attribute of the previous character displayed at the same position. 


Call with: AH = 0AH 
AL = character 
BH = page 
BL = color (graphics modes, PCjr only) 
CX = count of characters to write (replication factor) 


nn tte 


Returns: Nothing 


ee 


Notes: = In graphics modes, the replication factor in CX produces a valid result only for the 
current row. If more characters are written than there are remaining columns in the 
current row, the result is unpredictable. 


= All values of AL result in some sort of display; control characters, including bell, 
backspace, carriage return, and line feed, are not recognized as special characters 
and do not affect the cursor position. 
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™ After a character is written, the cursor must be moved explicitly with Int 10H Func- 
tion 02H to the next position. 


= To write a character and attribute at the current cursor position, use Int 10H Func- 
tion 09H. 


= If this function is used to write characters in graphics mode and bit 7 of BL is set (1), 
the character will be exclusive-OR’d (XOR) with the current display contents. This 
feature can be used to write characters and then “erase” them. 

= For the CGA and PCjr in graphics modes 04H-06H, the bit patterns for character 
codes 80H-FFH are obtained from a table whose address is stored in the vector for 
Int 1FH. On the PCjr, the address of the table for character codes 0OH-7FH is stored 
in the vector for Int 44H. Alternative character sets may be installed by loading them 
into memory and updating this vector. 

@ For the EGA, MCGA, and VGA in graphics modes, the address of the character defini- 
tion table is stored in the vector for Int 43H. See Int 10H Function 11H. 


SSS sii s eset Ssssstessssessseesssssesssn 


Int 10H 


[CGA] [PCjr] [EGA] [MCGA] [VGA] 


Function 0BH (11) 
Set palette, background, or border 


Selects a palette, background, or border color, 


Call with: 


To set the background color and border color for graphics modes or the border color for 
text modes 


AH = OBH 

BH = 00H 

BL = color 

To select the palette (320-by-200 4-color graphics modes) 
AH = 0OBH 

BH = 01H 

BL = palette (see Notes) 


— ee 


Returns: 


Notes: 


Nothing 


™ In text modes, this function selects only the border color. The background color 
of each individual character is controlled by the upper 4 bits of that character’s 
attribute byte. 

= On the CGA and EGA, this function is valid for palette selection only in 320-by-200 
4-color graphics modes. 


508 Section III 


® In 320-by-200 4-color graphics modes, if register BH = 01H, the following palettes 
may be selected: 
Palette Pixelvalue Color 


0 0 same as background 
1 green 
2 red 
3 brown or yellow 

1 0 same as background 
1 cyan 
2 magenta 
3 white 


= On the CGA in 640-by-200 2-color graphics mode, the background color selected 
with this function actually controls the display color for nonzero pixels; zero pixels 
are always displayed as black. 


= On the PCjr in 640-by-200 2-color graphics mode, if BH = 00H and bit 0 of register BL 
is cleared, pixel value 1 is displayed as white; if bit 0 is set, pixel value 1 is displayed 
as black. 


= See also Int 10H Function 10H, which is used for palette programming on the PCjr, 
EGA, MCGA, and VGA. 


A a Sa 


Int 10H [CGA] [PCjr] [EGA] [MCGA] [VGA] 
Function 0CH (12) 


Write graphics pixel 
a 


Draws a point on the display at the specified graphics coordinates. 


Caliwith: AH = 0CH 
AL = pixel value 
BH = page 
CX = column (graphics x coordinate) 
DX = row (graphics y coordinate) 


Returns: Nothing 


SS 


Notes: = The range of valid pixel values and (x,y) coordinates depends on the current 
video mode. 


= If bit 7 of AL is set, the new pixel value will be exclusive-OR’d (XOR) with the 
current contents of the pixel. 


™ Register BH is ignored for display modes that support only one page. 
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—————— 
Int 10H [CGA] [PCjr] [EGA] [MCGA] [VGA] 


Function 0DH (13) 
Read graphics pixel 


Obtains the current value of the pixel on the display at the specified graphics coordinates. 


eee 
Call with: AH = 0DH 


BH = page 
CX = column (graphics x coordinate) 
DX = row (graphics y coordinate) 


Returns: AL = pixel value 


Notes: = The range of valid (x,y) coordinates and possible pixel values depends on the 
current video made. 


™ Register BH is ignored for display modes that support only one page. 


————— 
Int 10H [MDA] [CGA] [PCjr] [EGA] [MCGA] [VGA] 


Function OEH (14) 
Write character in teletype mode 


Writes an ASCII character to the display at the current cursor position, using the specified color Cif in 
graphics modes), and then increments the cursor position appropriately. 


eee 
Call with: AH = 0EH 


AL = character 
BH = page 
BL = foreground color (graphics modes) 


eee 
Returns: Nothing 


eee 

Notes: m™ The special ASCII codes for bell (07H), backspace (08H), carriage return (ODH), and 
line feed (OAH) are recognized, and the appropriate action is taken. All other char- 
acters are written to the display (even if they are control characters), and the cursor 
is moved to the next position. 


= In video modes that support multiple pages, characters can be written to any page, 
regardless of the page currently being displayed. 


™ Line wrapping and scrolling are provided. If the cursor is at the end of a line, it is 
moved to the beginning of the next line. If the cursor reaches the end of the last line 
on the screen, the screen is scrolled up by one line and the cursor is placed at the 
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beginning of a new blank line. The attribute for the entire new line is taken from the 
last character that was written on the preceding line. 

= The default MS-DOS console driver (CON) uses this function to write text to the 
screen. You cannot use this function to specify the attribute of a character. One 
method of writing a character to the screen with a specific attribute is to first write 
an ASCII blank (20H) with the desired attribute at the current cursor location using 
Int 10H Function 09H and then write the actual character with Int 10H Function 
OEH. This technique, although somewhat clumsy, does not require the program to 
explicitly handle line wrapping and scrolling. 

= See also Int 10H Function 13H. 


a 


Int 10H [MDA] [CGA] [PCjr] [EGA] [MCGA] [VGA] 
Function OFH (15) 


Get video mode 


a 


Obtains the current display mode of the active video controller. 


I 


Call with: AH = OFH 
I TT 
Returns: AH = number of character columns on screen 

AL = display mode (see Int 10H Function 00H) 

BH = active display page 
Note: = This function can be called to obtain the screen width before clearing the screen 


with Int 10H Functions 06H or 07H. 


ee 


Int 10H [PCjr] [EGA] [MCGA] [VGA] 
Function 10H (16) Subfunction 00H 
Set palette register 


a 


Sets the correspondence of a palette register to a displayable color. 


I (I 


Call with: = On the PCjr, EGA, or VGA 


AH = 10H 

AL = 00H 

BH = color value 

BL = palette register (00O—OFH) 
On the MCGA 

AH = 10H 

AL = 00H 

BX = 0712H 
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nee 


Returns; Nothing 


Note: = On the MCGA, this function can only be called with BX = 0712H and selects a color 
register set with eight consistent colors. 


ee 


Int 10H [PCjr] [EGA] [VGA] 
Function 10H (16) Subfunction 01H 
Set border color 


Controls the color of the screen border (overscan). 
TO ae 
Callwith: AH = 10H 

AL = 01H 

BH = color value 


ene 


Returns: Nothing 


eee 


Int 10H [PCjr] [EGA] [VGA] 
Function 10H (16) Subfunction 02H 
Set palette and border 


Sets all palette registers and the border color (overscan) in one operation. 
eee 
Call with: AH = 10H 

AL = 02H 

ES:DX = segment:offset of color list 


eee 


Returns: Nothing 


Notes: = The color list is 17 bytes long. The first 16 bytes are the color values to be loaded into 
palette registers 0-15, and the last byte is stored in the border color register. 


# In 16-color graphics modes, the following default palette is set up: 
Pixelvalue Color 


01H blue 
02H green 
03H cyan 
04H red 

05H magenta 
06H brown 
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Pixelvalue Color 


07H white 

08H gray 

09H light blue 

OAH light green 

OBH light cyan 

0CH light red 

ODH light magenta 

OEH yellow 

OFH intense white 
Int 10H [PCjr] [EGA] [MCGA] [VGA] 
Function 10H (16) Subfunction 03H 
Toggle blink/intensity bit 


5 To a 
Determines whether the most significant bit of a character attribute will select blinking or intensified 
display. 


Call with: AH = 10H 
AL = 03H 
BL = blink/intensity toggle 


O = enable intensity 
1 = enable blinking 


Returns: Nothing 


ae 


Int 10H [VGA] 
Function 10H (16) Subfunction 07H 
Get palette register 


a 


Returns the color associated with the specified palette register. 


Call with: AH = 10H 

AL = 07H 

BL = palette register 
Returns: BH = color 
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—————— 
Int 10H [VGA] 


Function 10H (16) Subfunction 08H 
Get border color 


Returns the current border color (overscan). 
Call with: AH = 10H 
AL = 08H 


eee 
Returns: BH = color 


SSS SSS 


Int 10H [VGA] 
Function 10H (16) Subfunction 09H 
Get palette and border 


Gets the contents of all palette registers and the border color (overscan) in one operation. 


OO eee 


Call with: AH = 10H 


AL = 09H 
ES:DX = segment:offset of 17-byte buffer 
Returns: ES:DX = segment:offset of buffer 


and buffer contains palette values in bytes OOH—OFH and border color in byte 10H. 


Sasi iiaSSsseeisSe Ss sseseses 


Int 10H [MCGA] [VGA] 
Function 10H (16) Subfunction 10H (16) 
Set color register 


Programs an individual color register with a red-green-blue (RGB) combination. 


a es 
Call with: AH = 10H 


AL = 10H 

BX = color register 
CH = green value 
CL = blue value 
DH ' = red value 
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Returns: Nothing 


Note: m If gray-scale summing is enabled, the weighted gray-scale value is calculated as 
described under Int 10H Function 10H Subfunction 1BH and is stored into all three 
components of the color register. See also Int 10H Function 12H Subfunction 33H. 


a Ss 


Int 10H [MCGA] [VGA] 
Function 10H (16) Subfunction 12H (18) 
Set block of color registers 


a a 


Programs a group of consecutive color registers in one operation. 


Call with: AH = 10H 
AL = 12H 
BX = first color register 
CX = number of color registers 
ES:DX = segment:offset of color table 


Returns: Nothing 


Notes: = The table consists of a series of 3-byte entries, one entry per color register to be pro- 
grammed. The bytes of an individual entry specify the red, green, and blue values 
(in that order) for the associated color register. 
™ If gray-scale summing is enabled, the weighted gray-scale value for each register is 
calculated as described under Int 10H Function 10H Subfunction 1BH and is stored 
into all three components of the color register. See also Int 10H Function 12H Sub- 
function 33H. 


A 


Int 10H [VGA] 
Function 10H (16) Subfunction 13H (19) 
Set color page state 


eS 


Selects the paging mode for the color registers, or selects an individual page of color registers. 


Call with: To select the paging mode 


AH = 10H 
AL = 13H 
BH = paging mode 
OOH for 4 pages of 64 registers 
01H for 16 pages of 16 registers 
BL = 00H 
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To select a color register page 


AH = 10H 
AL = 13H 
BH = page 
BL = 01H 


Ss as 5 i ee 


Returns: Nothing 


Note: ® This function is not valid in mode 13H (320-by-200 256-color graphics). 


ee 
Int 10H [MCGA] [VGA] 


Function 10H (16) Subfunction 15H (21) 


Get color register 
SU 


Returns the contents of a color register as its red, green, and blue components. 


a gg 


Call with: AH = 10H 
AL = 15H 
BX = color register 


Returns: CH = green value 


CL = blue value 

DH = red value 
LS nese sor ener 
Int 10H [MCGA] [VGA] 


Function 10H (16) Subfunction 17H (23) 
Get block of color registers 


Allows the red, green, and blue components associated with each of a set of color registers to be read in 
one operation. 


eee 
Call with: AH = 10H 


AL = 17H 

BX = first color register 

CX = number of color registers 

ES:DX = segment:offset of buffer to receive color list 
Returns: ES:DX = segment:offset of buffer 


and buffer contains color list 
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Note: The color list returned in the caller’s buffer consists of a series of 3-byte entries cor- 
responding to the color registers. Each 3-byte entry contains the register’s red, green, 
and blue components in that order. 


Int 10H [VGA] 
Function 10H (16) Subfunction 1AH (26) 
Get color page state 


Returns the color register paging mode and current color page. 


Call with: AH = 10H 
AL = 1AH 
Returns: BH = color page 
BL = paging mode 
OOH if 4 pages of 64 registers 
01H if 16 pages of 16 registers 
Note: See Int 10H Function 10H Subfunction 13H, which allows selection of the paging 


mode or current color page. 


Int 10H [MCGA] [VGA] 
Function 10H (16) Subfunction 1BH (27) 
Set gray-scale values 


Transforms the red, green, and blue values of one or more color registers into the gray-scale equivalents. 


Call with: AH = 10H 
AL = 1BH 
BX = first color register 
CX = number of color registers 
Returns: Nothing : 
Note: m™ For each color register, the weighted sum of its red, green, and blue values is calcu- 


lated (30% red + 59% green + 11% blue) and written back into all three components 
of the color register. The original red, green, and blue values are lost. 
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ee 
Int 10H [EGA] [MCGA] [VGA] 
Function 11H (17) Subfunctions 00H and 10H (16) 

Load user font 


Loads the user’s font (character definition) table into the specified block of character generator RAM. 


Call with: AH = 11H 
AL = OOH or 10H (see Notes) 
BH = points (bytes per character) 
BL = block 
CX = number of characters defined by table 
DX = first character code in table 
ES:BP = segment:offset of font table 


a a a 
Returns: Nothing 


ee a ee ee 

Notes: ™ This function provides font selection in text (alphanumeric) display modes. For font 
selection in graphics (all-points-addressable) modes, see Int 10H Function 11H Sub- 
functions 20H-24H. 


= If AL= 10H, page 0 must be active. The points (bytes per character), rows, and 
length of the refresh buffer are recalculated. The controller is reprogrammed with 
the maximum scan line (points— 1), cursor start (points — 2), cursor end (points — 
1), vertical display end ((rows+ points) — 1), and underline location (points — 1, 
mode 7 only). 
If Subfunction 10H is called at any time other than immediately after a mode set, the 
results are unpredictable. 


m On the MCGA, a Subfunction 00H call should be followed by a Subfunction 03H call 
so that the ROM BIOS will load the font into the character generator’s internal font 


pages. 
= Subfunction 10H is reserved on the MCGA. If it is called, Subfunction 00H is 
executed. 
Int 10H [EGA] [VGA] 


Function 11H (17) Subfunctions 01H and 11H (17) 
Load ROM 8-by-14 font 


Loads the ROM BIOS default 8-by-14 font table into the specified block of character generator RAM. 


Call with: AH = 11H 
AL = 01H or 11H (See Notes) 
BL = block 
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Returns: Nothing 


Notes: = #® This function provides font selection in text (alphanumeric) display modes. For font 
selection in graphics (all-points-addressable) modes, see Int 10H Function 11H Sub- 
functions 20H—24H. 


= If AL= 11H, page 0 must be active. The points (bytes per character), rows, and 
length of the refresh buffer are recalculated. The controller is reprogrammed with 
the maximum scan line (points— 1), cursor start (points — 2), cursor end (points — 
1), vertical display end (Crows* points) — 1), and underline location (points — 1, 
mode 7 only). 


If Subfunction 11H is called at any time other than immediately after a mode set, the 
results are unpredictable. 


= Subfunctions 01H and 11H are reserved on the MCGA. If either is called, Subfunction 
04H is executed. 


Int 10H [EGA] [MCGA] [VGA] 
Function 11H (17) Subfunctions 02H and 12H (18) 
Load ROM 8-by-8 font 


Loads the ROM BIOS default 8-by-8 font table into the specified block of character generator RAM. 


Call with: AH = 11H 
AL = 02H or 12H (see Notes) 
BL = block 


Returns: Nothing 


Notes: ® This function provides font selection in text (alphanumeric) display modes. For font 
selection in graphics (all-points-addressable) modes, see Int 10H Function 11H Sub- 
functions 20H-24H. 


= If AL= 12H, page 0 must be active. The points (bytes per character), rows, and 
length of the refresh buffer are recalculated. The controller is reprogrammed with 
the maximum scan line (points — 1), cursor start (points — 2), cursor end (points — 
1), vertical display end (Crows+ points) — 1), and underline location (points — 1, 
mode 7 only). 
If Subfunction 12H is called at any time other than immediately after a mode set, the 
results are unpredictable. 

m™ On the MCGA, a Subfunction 02H call should be followed by a Subfunction 03H call, 
so that the ROM BIOS will load the font into the character generator’s internal font 
pages. 

= Subfunction 12H is reserved on the MCGA. If it is called, Subfunction 02H is 
executed. 
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Int 10H [EGA] [MCGA] [VGA] 
Function 11H (17) Subfunction 03H 
Set block specifier 


LS ASS SSS SSS eS 
Determines the character blocks selected by bit 3 of character attribute bytes in alphanumeric (text) 
display modes. 


Call with: AH = 11H 
AL = 03H 
BL = character generator block select code (see Notes) 


Returns: Nothing 


Notes: ™ On the EGA and MCGA, the bits of BL are used as follows: 

Bits Significance 

0-1 character block selected by attribute bytes with bit 3 = 0 
2-3 character block selected by attribute bytes with bit 3 = 1 
4-7 not used (should be 0) 

= On the VGA, the bits of BL are used as follows: 

Bits Significance 

0,1,4 character block selected by attribute bytes with bit 3 = 0 
2,3,5 character block selected by attribute bytes with bit 3 = 1 
6-7 not used (should be 0) 


= When using a 256-character set, both fields of BL should select the same character 
block. In such cases, character attribute bit 3 controls the foreground intensity. 
When using 512-character sets, the fields of BL designate the blocks holding each 
half of the character set, and bit 3 of the character attribute selects the upper or 
lower half of the character set. 

= When using a 512-character set, a call to Int 10H Function 10H Subfunction 00H 
with BX = 0712H is recommended to set the color planes to eight consistent colors. 


ee 


Int 10H [MCGA] [VGA] 
Function 11H (17) Subfunctions 04H and 14H (20) 
Load ROM 8-by-16 font 


SS SS I SS se es 
Loads the ROM BIOS default 8-by-16 font table into the specified block of character generator RAM. 


Call with: AH = 11H 
AL = 04H or 14H (see Notes) 
BL = block 
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Returns: Nothing 


Notes: m This function provides font selection in text (alphanumeric) display modes. For font 
selection in graphics (all-points-addressable) modes, see Int 10H Function 11H Sub- 
functions 20H-24H. 


m If AL = 14H, page 0 must be active. The points (bytes per character), rows, and 
length of the refresh buffer are recalculated. The controller is reprogrammed with 
the maximum scan line (poinis— 1), cursor start (points — 2), cursor end (points — 
1), vertical display end (rows+ points — 1 for 350- and 400-line modes, or rows 
+ points «2 — 1 for 200-line modes), and underline location (points — 1, mode 7 
only). 

If Subfunction 14H is called at any time other than immediately after a mode set, the 
results are unpredictable. 


@ On the MCGA, a Subfunction 04H call should be followed by a Subfunction 03H call 
so that the ROM BIOS will load the font into the character generator’s internal font 
pages. 

w Subfunction 14H is reserved on the MCGA. If it is called, Subfunction 04H is 
executed. 


Int 10H [EGA] [MCGA] [VGA] 
Function 11H (17) Subfunction 20H (32) 
Set Int 1FH font pointer 


Sets the Int IFH pointer to the user’s font table. This table is used for character codes 80H-FFH in 
graphics modes 04H—06H. 


Call with: AH = 11H 
AL = 20H 
ES:BP = segment:offset of font table 


Returns: Nothing 


Note: a This function provides font selection in graphics (all-points-addressable) display 
modes. For font selection in text (alphanumeric) modes, see Int 10H Function 11H 
Subfunctions OOH-14H. 


m If this subfunction is called at any time other than immediately after a mode set, the 
results are unpredictable. 
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Int 10H | [EGA] [MCGA] [VGA] 
Function 11H (17) Subfunction 21H (33) 
Set Int 43H for user’s font 


Sets the vector for Int 43H to point to the user’s font table and updates the video ROM BIOS data area. The 
video controller is not reprogrammed. 


Call with: AH = 11H 

AL = 21H 

BL = character rows specifier 
OOH if user specified (see register DL) 
01H = 14 (OEH) rows 
02H = 25 (19H) rows 
03H = 43 (2BH) rows 

CX = points (bytes per character) 

DL = character rows per screen (if BL = 00H) 

ES:BP = segment:offset of user font table 


Returns: Nothing 


Notes: ™ This function provides font selection in graphics (all-points-addressable) display 
modes. For font selection in text (alphanumeric) modes, see Int 10H Function 11H 
Subfunctions 0OH-14H. 


= If this subfunction is called at any time other than immediately after a mode set, the 
results are unpredictable. 


Int 10H [EGA] [MCGA] [VGA] 
Function 11H (17) Subfunction 22H (34) 
Set Int 43H for ROM 8-by-14 font 


Sets the vector for Int 43H to point to the ROM BIOS default 8-by-14 font and updates the video ROM BIOS 
data area. The video controller is not reprogrammed. 


Callwith: AH = 11H 

AL = 22H 

BL = character rows specifier 
OOH if user specified (see register DL) 
01H = 14 (OEH) rows 
02H = 25 (19H) rows 
03H = 43 (2BH) rows 

DL = character rows per screen (if BL = 00H) 
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Returns: Nothing 


Notes: ™ This function provides font selection in graphics (all-points-addressable) display 
modes. For font selection in text (alphanumeric) modes, see Int 10H Function 11H 
Subfunctions OOH-14H. 
@ If this subfunction is called at any time other than immediately after a mode set, the 
results are unpredictable. 


@ When this subfunction is called on the MCGA, Subfunction 24H is substituted. 


Int 10H [EGA] [MCGA] [VGA] 
Function 11H (17) Subfunction 23H (35) 
Set Int 43H for ROM 8-by-8 font 


Sets the vector for Int 43H to point to the ROM BIOS default 8-by-8 font and updates the video ROM BIOS 
data area. The video controller is not reprogrammed. 


Call with: AH = 11H 

AL = 23H 

BL = character rows specifier 
OOH if user specified (see register DL) 
01H = 14 (OEH) rows 
02H = 25 (19H) rows 
03H = 43 (2BH) rows 

DL = character rows per screen (if BL = 00H) 


Returns: Nothing 


Notes: ™ This function provides font selection in graphics (all-points-addressable) display 
modes. For font selection in text (alphanumeric) modes, see Int 10H Function 11H 
Subfunctions OOH-14H. 


™ If this subfunction is called at any time other than immediately after a mode set, the 
results are unpredictable. 


Int 10H [MCGA] [VGA] 
Function 11H (17) Subfunction 24H (36) 
Set Int 43H for ROM 8-by-16 font 


Sets the vector for Int 43H to point to the ROM BIOS default 8-by-16 font and updates the video ROM BIOS 
data area. The video controller is not reprogrammed. 
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Call with: AH = 11H 


AL = 24H 
BL = row specifier 
OOH if user specified (see register DL) 
01H = 14 (OEH) rows 
02H = 25 (19H) rows 
03H = 43 (2BH) rows 
DL = character rows per screen (if BL = 00H) 


Returns: Nothing 


9 


Note: ™ This function provides font selection in graphics (all-points-addressable) display 
modes. For font selection in text (alphanumeric) modes, see Int 10H Function 11H 
Subfunctions 0OOH-14H. 


® If this subfunction is called at any time other than immediately after a mode set, the 
results are unpredictable. 


Int 10H [EGA] [MCGA] [VGA] 
Function 11H (17) Subfunction 30H (48) 
Get font information 


_ Returns a pointer to the character definition table for a font and the points (bytes per character) and rows 
for that font. 


Callwith: AH = 11H 
AL = 30H 
BH = font code 
OOH = current Int 1FH contents 
O1H = current Int 43H contents 
02H = ROM 8-by-14 font (EGA, VGA only) 
03H = ROM 8-by-8 font (characters OOH—7FH) 
04H = ROM 8-by-8 font (characters 8SOH-FFH) 
05H = ROM alternate 9-by-14 font (EGA, VGA only) 
06H = ROM 8-by-16 font (MCGA, VGA only) 
O7H = ROM alternate 9-by-16 font (VGA only) 
Returns: CX = points (bytes per character) 
DL = rows (character rows on screen — 1) 
ES:BP = segment:offset of font table 
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Int 10H [EGA] [VGA] 
Function 12H (18) Subfunction 10H (16) 
Get configuration information 


Obtains configuration information for the active video subsystem. 


Call with: AH = 12H 
BL = 10H 
Returns: BH = display type 
O if color display 
1 if monochrome display 
BL = memory installed on EGA board 
OOH if 64 KB 
01H if 128 KB 
02H if 192 KB 
03H if 256 KB 
CH = feature bits (see Notes) 
CL = switch setting (see Notes) 
Notes: = The feature bits are set from Input Status register 0 in response to an output on the 


specified Feature Control register bits: 
Feature Feature control Input status 


bit(s) output bit bit 
0 0 5 

1 0 6 

2 1 5 

3 1 6 
4-7 not used 


= The bits in the switch settings byte indicate the state of the EGA’s configuration DIP 
switch (1 = off, 0 = on). 
Bit(s) Significance 


0 configuration switch 1 
1 configuration switch 2 
2 configuration switch 3 
3 configuration switch 4 
4-7 not used 
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Int 10H | [EGA] [VGA] 
Function 12H (18) Subfunction 20H (32) 
Select alternate printscreen 


Selects an alternate print-screen routine for the EGA and VGA that works properly if the screen length is 
not 25 lines. The ROM BIOS default print-screen routine always prints 25 lines. 


Call with: AH = 12H 
BL = 20H 


Returns: Nothing 


Int 10H [VGA] 
Function 12H (18) Subfunction 30H (48) 
Set scan lines 


Selects the number of scan lines for alphanumeric modes. The selected value takes effect the next time Int 
10H Function 00H is called to select the display mode. 


Call with: AH = 12H 
AL = scan line code 
OOH = 200 scan lines 
01H = 350 scan lines 
02H = 400 scan lines 
BL = 30H 


Returns: If the VGA is active 


AL = 12H 
If the VGA is not active 
AL = 00H 
Int 10H [MCGA] [VGA] 


Function 12H (18) Subfunction 31H (49) 
Enable/disable default palette loading 


Enables or disables loading of a default palette when a video display mode is selected. 
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Call with: AH = 12H 


AL = QOH to enable default palette loading 
01H to disable default palette loading 

BL = 31H 
Returns: If function supported 

AL = 12H 
Int 10H [MCGA] [VGA] 
Function 12H (18) Subfunction 32H (50) 
Enable/disable video 


Enables or disables CPU access to the video adapter’s I/O ports and video refresh buffer. 


Call with: AH = 12H 
AL = QOH to enable access 
01H to disable access 
BL = 32H 
Returns: If function supported 
AL = 12H 
Int 10H [MCGA] [VGA] 


Function 12H (18) Subfunction 33H (51) 
Enable/disable gray-scale summing 


Enables or disables gray-scale summing for the currently active display. 


Call with: AH = 12H 
AL = QOH to enable gray-scale summing 
01H to disable gray-scale summing 

BL = 33H 


Returns: If function supported 
AL = 12H 


Note: = When enabled, gray-scale summing occurs during display mode selection, palette 
programming, and color register loading. 
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Int 10H [VGA] 
Function 12H (18) Subfunction 34H (52) 
Enable/disable cursor emulation 


Enables or disables cursor emulation for the currently active display. When cursor emulation is enabled, 
the ROM BIOS automatically remaps Int 10H Function 01H cursor starting and ending lines for the current 
character cell dimensions. 


Call with: AH = 12H 
AL = OOH to enable cursor emulation 
01H to disable cursor emulation 

BL = 34H 


Returns: If function supported 
AL = 12H 


Int 10H [MCGA] [VGA] 
Function 12H (18) Subfunction 35H (53) 
Switch active display 


Allows selection of one of two video adapters in the system when memory usage or port addresses 
conflict between the two adapters. 


Callwith: AH = 12H 

AL = switching function 
OOH to disable initial video adapter 
01H to enable system board video adapter 
02H to disable active video adapter 
03H to enable inactive video adapter 

BL = 35H 

ES:DX = segment:offset of 128-byte buffer Cif AL = OOH, 02H, or 03H) 


Returns: If function supported 
AL = 12H 
and, if called with AL = 00H or 02H 
Video adapter state information saved in caller’s buffer 


or, if called with AL = 03H 
Video adapter state restored from information in caller’s buffer 
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Notes: m This subfunction cannot be used unless both video adapters have a disable capa- 
bility (int 10H Function 12H Subfunction 32H). 
m If there is no conflict between the system board video and the adapter board video 


in memory or port usage, both video controllers can be active simultaneously and 
this subfunction is not required. 


Int 10H [VGA] 
Function 12H (18) Subfunction 36H (54) 
Enable/disable screen refresh 


Enables or disables the video refresh for the currently active display. 


Call with: AH = 12H 
AL = QOH to enable refresh 
01H to disable refresh 

BL = 36H 


Returns: If function supported 
| AL = 12H 


Int 10H [MDA] [CGA] [PCjr] [EGA] [MCGA] [VGA] 
Function 13H (19) 
Write string in teletype mode 


Transfers a string to the video buffer for the currently active display, starting at the specified position. 


Call with: AH = 13H 
AL = write mode 

O attribute in BL; 
string contains character codes only; and cursor position is not 
updated after write 

1 attribute in BL; 
string contains character codes only; and cursor position is 
updated after write 

2 string contains alternating character codes and attribute bytes, 
and cursor position is not updated after write 

4 string contains alternating character codes and attribute bytes, 
and cursor position is updated after write 
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BH = page 


BL = attribute, if AL = 00H or 01H 
CX = length of character string 
DH = y coordinate (row) 

DL = x coordinate (column) 
ES:BP = segment:offset of string 


ee, 2 ee 
Returns: Nothing 


Notes: a This function is not available on the original IBM PC or PC/XT unless an EGA video 
adapter (which contains its own ROM BIOS) is installed. 
m This function may be thought of as an extension to Int 10H Function OEH. The con- 
trol characters bell (07H), backspace (08H), line feed (OAH), and carriage return 
(ODH) are recognized and handled appropriately. 


Int 10H [PS/2] 
Function 1AH (26) 
Get or set display combination code 


Returns a code describing the installed display adapter(s) or updates the ROM BIOS’s variable describing 
the installed adapter(s). 


Call with: AH = 1AH 
AL = subfunction 
OOH = get display combination code 
O1H = Set display combination code 
BH = inactive display code Cif AL = 01H) 
BL = active display code Cif AL = 01H) 


Returns: If function supported 


AL = 1AH 
and, if called with AL = 0OH 
BH = inactive display code 
BL = active display code 
ns sg Se 
Note: m The display codes are interpreted as follows: 
Code(s) Video subsystem type 
00H no display 
01H MDA with 5151 monitor 
02H CGA with 5153 or 5154 monitor 
03H reserved 
04H EGA with 5153 or 5154 monitor 
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Code(s) Video subsystem type 


05H EGA with 5151 monitor 

06H PGA with 5175 monitor 

07H VGA with analog monochrome monitor 
08H VGA with analog color monitor 

09H reserved 

OAH MCGA with digital color monitor 

OBH MCGA with analog monochrome monitor 
0CH MCGA with analog color monitor 
ODH-FEH reserved 

FFH unknown 


Ln 


Int 10H [PS/2] 
Function 1BH (27) 
Get functionality/state information 


a SS 
Obtains information about the current display mode as well as a pointer to a table describing the charac- 
teristics and capabilities of the video adapter and monitor. 


Call with: AH = 1BH 
BX = implementation type (always 00H) 
ES:DI = segment:offset of 64-byte buffer 
Returns: If function supported 
AL = 1BH 


and information placed in caller’s buffer (see Notes) 


Notes: = The caller’s buffer is filled in with information that depends on the current video 
display mode: 
Byte(s) Contents 
00H-03H pointer to functionality information (see next Note) 
04H current video mode 
0SH-06H number of character columns 
07H—08H _ length of video refresh buffer (bytes) 
09H-OAH _ starting address in buffer of upper left corner of display 
OBH-1AH cursor position for video pages 0-7 as eight 2-byte entries; first byte of 
each pair is y coordinate, second byte is x coordinate 


1BH cursor starting line 

1CH cursor ending line 

1DH active display page 

1EH-1FH adapter base port address (3BXH monochrome, 3DXH color) 
20H current setting of register 3B8H or 3D8H 
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Byte(s) 


Section IT 


21H 
22H 
23H-—24H 
25H 
26H 
27H-28H 
29H 
2AH 


2BH 
2CH 
2DH 


2ZEH-30H 
31H 


32H 


33H-3FH 


Contents 

current setting of register 3B9H or 3D9H 

number of character rows 

character height in scan lines 

active display code (see Int 10H Function 1AH) 
inactive display code (see Int 10H Function 1AH) 
number of displayable colors (0 for monochrome) 


number of display pages 
number of scan lines 

OOH = 200 scan lines 
O1H = 350 scan lines 
02H = 400 scan lines 
03H = 480 scan lines 


O4H-FFH = reserved 

primary character block (see Int 10H Function 11H Subfunction 03H) 
secondary character block 

miscellaneous state information 

Bit(s) Significance 


0 = 1 if all modes on all displays active (always 0 on MCGA) 
1 = 1 if gray-scale summing active 

2 = 1 if monochrome display attached 

3 = 1 if mode set default palette loading disabled 

4 = 1 if cursor emulation active (always 0 on MCGA) 
5 = state of I/B toggle (0 = intensity, 1 = blink) 

6-7 = reserved 

reserved 

video memory available 

OOH = 64 KB 

O1H = 128 KB 

02H = 192 KB 

03H = 256 KB 


save pointer state information 
Bit(s) Significance 


0 = 1 if 512-character set active 

1 = 1 if dynamic save area active 

2 = 1 if alpha font override active 

3 = 1 if graphics font override active 

4 = 1 if palette override active 

5 = 1 if display combination code (DCC) extension active 
6-7 = reserved 

reserved 


m Bytes 0-3 of the caller’s buffer contain a DWORD pointer (offset in lower word, 
segment in upper word) to the following information about the display adapter 
and monitor: 

Byte(s) Contents 


00H video modes supported 
Bit Significance 
0 = 1 if mode 00H supported 
1 = 1 if mode 01H supported 
2 = 1 if mode 02H supported 
3 = 1 if mode 03H supported 
4 = 1 if mode 04H supported 
5 = 1 if mode 05H supported 
6 = 1 if mode 06H supported 
7 = 1 if mode 07H supported 
01H video modes supported 
Bit Significance 
0 = 1 if mode 08H supported 
1 = 1 if mode 09H supported 
2 = 1 if mode OAH supported 
3 = 1 if mode OBH supported 
4 = 1 if mode OCH supported 
5 = 1 if mode ODH supported 
6 = 1 if mode OEH supported 
7 = 1 if mode OFH supported 
02H video modes supported 
Bit(s) Significance 
0 = 1 if mode 10H supported 
1 = 1 if mode 11H supported 
2 = 1 if mode 12H supported 
3 = 1 if mode 13H supported 
4-7 = reserved 
03H-06H _ reserved 
07H scan lines available in text modes 
Bit(s) Significance 
0 = 1 if 200 scan lines 
1 = 1 if 350 scan lines 
2 = 1 if 400 scan lines 
3-7 = reserved 
08H character blocks available in text modes (see Int 10H Function 11H) 
09H maximum number of active character blocks in text modes 
OAH miscellaneous BIOS capabilities 
Bit Significance 
0 = 1 if all modes active on all displays (always 0 for MCGA) 
1 = 1 if gray-scale summing available 
2 = 1 if character font loading available 
3 = 1 if mode set default palette loading available 
4 = 1 if cursor emulation available 
5 = 1 if EGA (64-color) palette available 
6 = 1 if color register loading available 
7 = 1 if color register paging mode select available 
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Byte(s) Contents 


OBH miscellaneous BIOS capabilities 
Bit(s) Significance 
0 = 1 if light pen available 
1 = 1 if save/restore video state available (always 0 on 
MCGA) 
2 = 1 if background intensity/blinking control available 
3 = 1 if get/set display combination code available 
4-7 = reserved 
OCH-ODH reserved 
0OEH save area capabilities 


Bit(s) Significance 
0 = 1 if supports 512-character sets 
1 = 1 if dynamic save area available 
2 = 1 if alpha font override available 
3 = 1 if graphics font override available 
4 = 1 if palette override available 
= 1 if display combination code extension available 
~7 = reserved 
OFH reserved 


———— 
Int 10H [PS/2] 


Function 1CH (28) 
Save or restore video state 


ON WT 


Saves or restores the digital-to-analog converter (DAC) state and color registers, ROM BIOS video driver 
data area, or video hardware state. 


ee 
Call with: AH = 1CH 


AL = subfunction 
OOH to get state buffer size 
O1H to save state 
02H to restore state 

CX = requested states 
Bit(s) Significance (if set) 
0 save/restore video hardware state 
1 save/restore video BIOS data area 
2 save/restore video DAC state and color registers 
3-15 reserved 

ES:BX = segment:offset of buffer 


i es 
Returns: If function supported 


AL = 1CH 
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and, if called with AL = 00H 

BX = buffer block count (64 bytes per block) 

or, if called with AL = 01H 

State information placed in caller’s buffer 

or, if called with AL = 02H 

Requested state restored according to contents of caller’s buffer 


Notes: = Subfunction 00H is used to determine the size of buffer that will be necessary to 
contain the specified state information. The caller must supply the buffer. 
= The current video state is altered during a save state operation (AL = 01H). If the 
requesting program needs to continue in the same video state, it can follow the save 
state request with an immediate call to restore the video state. 


= This function is supported on the VGA only. 


Int 11H [PC] [AT] [PS/2] 
Get equipment configuration 


Obtains the equipment list code word from the ROM BIOS. 


Call with: Nothing 


Returns: AX = equipment list code word 
Bit(s) Significance 
0 = 1 if floppy disk drive(s) installed 
1 = 1 if math coprocessor installed 
2 = 1 if pointing device installed (PS/2) 
2-3 system board ram size (PC, see Note) 
00 = 16 KB 
01 = 32 KB 
10 = 48 KB 
11 = 64 KB 
4-5 initial video mode 
00 reserved 
01 40-by-25 color text 
10 80-by-25 color text 
11 80-by-25 monochrome 
6-7 number of floppy disk drives Gf bit 0 = 1) 
00 =] 
01 =2 
10 = 3 
11 =4 
8 reserved 
9-11 number of RS-232 ports installed 
12 = 1 if game adapter installed 
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Bit(s) Significance 


13 = 1 if internal modem installed (PC and XT only) 
= 1 if serial printer attached (PCjr) 
14-15 number of printers installed 
Note: = Bits 2-3 of the returned value are used only in the ROM BIOS for the original 


IBM PC with the 64 KB system board and on the PCjr. 
SS seesaeeeseeenes 
Int 12H | [PC] [AT] [PS/2] 
Get conventional memory size 
sss 


Returns the amount of conventional memory available for use by MS-DOS and application programs. 


Call with: Nothing 


Returns: AX = memory size (in KB) 


Notes: = On some early PC models, the amount of memory returned by this function is con- 
trolled by the settings of the dip switches on the system board and may not reflect 
all the memory that is physically present. 


= On the PC/AT, the value returned is the amount of functional memory found during 
the power-on self-test, regardless of the memory size configuration information 
stored in CMOS RAM. 


= The value returned does not reflect any extended memory (above the 1 MB bound- 
ary) that may be installed on 80286 or 80386 machines such as the PC/AT or PS/2 
(Models 50 and above). 


ee 
Int 13H [PC] [AT] [PS/2] 


Function 00H 
Reset disk system 


Resets the disk controller, recalibrates its attached drives (the read/write arm is moved to cylinder 0), and 
prepares for disk I/O. 


Call with: AH = 00H 
DL = drive 
OOH-—7FH floppy disk 
SOH-FFH fixed disk 
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Returns: If function successful 
Carry flag =clear 
AH = 00H 
If function unsuccessful 
Carry flag =set 
AH = status (see Int 13H Function 01H) 


Notes: ® This function should be called after a failed floppy disk Read, Write, Verify, or For- 
mat request before retrying the operation. 


= If called with DL >= 80H (ie., selecting a fixed disk drive), the floppy disk controller 
and then the fixed disk controller are reset. See also Int 13H Function 0DH, which 
allows the fixed disk controller to be reset without affecting the floppy disk 
controller. 


Int 13H 7 [PC] [AT] [PS/2] 
Function 01H | 
Get disk system status 


Returns the status of the most recent disk operation. 


Call with: AH = 01H 
DL = drive 
OOH-—7FH floppy disk 
SOH-FFH fixed disk 


Returns: AH = 00H 
AL = status of previous disk operation 
OOH no error 


01H invalid command 

02H address mark not found 

03H disk write-protected (F) 

04H sector not found 

05H reset failed (HD) 

06H floppy disk removed (F) 

07H bad parameter table (HD 

08H DMA overrun (F) 

O9H DMA crossed 64 KB boundary 

OAH bad sector flag (HD) 

OBH bad track flag (FD 

OCH media type not found (F) 

ODH invalid number of sectors on format (FD 
OEH control data address mark detected (HD) 
OFH DMA arbitration level out of range (AD 
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10H uncorrectable CRC! or ECC? data error 
11H ECC corrected data error (HD 

20H controller failed 

40H seek failed 

SOH disk timed-out (failed to respond) 

AAH drive not ready (H) 

BBH undefined error (H) 

CCH write fault (HD 

EOH status register error (H) 

FFH sense operation failed (HD) 


H = fixed disk only, F = floppy disk only 


1 Cyclic Redundancy Check code 
2 Error Checking and Correcting code 


Note: ™ On fixed disks, error code 11H (ECC data error) indicates that a recoverable error 
was detected during a preceding Read Sector (Int 13H Function 02H) function. 


———— eee 
Int 13H [PC] [AT] [PS/2] 


Function 02H 
Read sector 


SS SSS isis isle se 


Reads one or more sectors from disk into memory. 


Call with: AH = 02H. 
AL = number of sectors 
CH = cylinder 
CL = sector 
DH = head 
DL = drive 


OOH—7FH floppy disk 
SOH-FFH fixed disk 
ES:BX = segment:offset of buffer 


—_—_—————- awe 


Returns: If function successful 
Carry flag =clear 
AH = 00H 
AL = number of sectors transferred 
If function unsuccessful 
Carry flag = set 
AH = status (see Int 13H Function 01H) 
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Notes: 


= On fixed disks, the upper 2 bits of the 10-bit cylinder number are placed in the up- 
per 2 bits of register CL. 


= On fixed disks, error code 11H indicates that a read error occurred that was cor- 
rected by the ECC algorithm; in this event, register AL contains the burst length. The 
data returned is probably good, although there is a small chance that the data was 
not corrected properly. If a multi-sector transfer was requested, the operation was 
terminated after the sector containing the read error. 


™ On floppy disk drives, an error may result from the drive motor being off at the time 
of the request. The ROM BIOS does not automatically wait for the drive to come up 
to speed before attempting the read operation. The requesting program should reset 
the floppy disk system (Int 13H Function 00H) and retry the operation three times 
before assuming that the error results from some other cause. 


a LL 


Int 13H 


[PC] [AT] [PS/2] 


Function 03H 
Write sector 


a 


Writes one or more sectors from memory to disk. 


Call with: 


AH = 03H 

AL = number of sectors 
CH = cylinder 

CL = sector 

DH = head 

DL = drive 


OOH-7FH floppy disk 
SOH-FFH fixed disk 
ES:BX = segment:offset of buffer 


Oe 


Returns: 


Notes: 


If function successful 

Carry flag =clear 

AH = 00H 

AL = number of sectors transferred 

If function unsuccessful 

Carry flag =set 

AH = status (see Int 13H Function 01H) 


® On fixed disks, the upper 2 bits of the 10-bit cylinder number are placed in the up- 
per 2 bits of register CL. 


™ On floppy disk drives, an error may result from the drive motor being off at the time 
of the request. The ROM BIOS does not automatically wait for the drive to come up 
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to speed before attempting the write operation. The requesting program should reset 
the floppy disk system (Int 13H Function 00H) and retry the operation three times 
before assuming that the error results from some other cause. 


—$—$—$<———— 
Int 13H [PC] [AT] [PS/2] 


Function 04H 
Verify sector 


Verifies the address fields of one or more sectors. No data is transferred to or from memory by this 
operation. 


i 


Call with: AH = 04H 


AL = number of sectors 
CH = cylinder 

CL = sector 

DH = head 

DL = drive 


OOH-7FH floppy disk 
SOH-FFH fixed disk 
ES:BX = segment:offset of buffer (see Notes) 


Returns: If function successful 
Carry flag =clear 
AH = 00H 
AL = number of sectors verified 


If function unsuccessful 
Carry flag = set 
AH = status (see Int 13H Function 01H) 


Notes: = On PCs, PC/XTs, and PC/ATs with ROM BIOS dated earlier than 11/15/85, ES:BX 
should point to a valid buffer. 


™ On fixed disks, the upper 2 bits of the 10-bit cylinder number are placed in the up- 
per 2 bits of register CL. 


= This function can be used to test whether a readable media is in a floppy disk drive. 
An error may result from the drive motor being off at the time of the request, 
because the ROM BIOS does not automatically wait for the drive to come up to 
speed before attempting the verify operation. The requesting program should reset 
the floppy disk system (Int 13H Function 00H) and retry the operation three times 
before assuming that a readable floppy disk is not present. 
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Int 13H 


[PC] [AT] [PS/2] 


Function 05H 
Format track 


a 


Initializes disk sector and track address fields on the specified track. 


Call with: 


AH = 05H 

AL = interleave (PC/XT fixed disks) 
CH = cylinder 

DH = head 

DL = drive 


OOH—-7FH floppy disk 
SOH-FFH fixed disk 
ES:BX = segment:offset of address field list (except PC/XT fixed disk, see Note) 


NN ni I 


Returns: 


Notes: 


If function successful 

Carry flag = clear 

AH = 00H 

If function unsuccessful 

Carry flag = set 

AH = status (see Int 13H Function 01H) 


= On floppy disks, the address field list consists of a series of 4-byte entries, one entry 
per sector, in the following format: 


Byte Contents 
0 cylinder 
1 head 
2 sector 
3 sector-size code 
OOH if 128 bytes per sector 
01H if 256 bytes per sector 
02H if 512 bytes per sector (standard) 
03H if 1024 bytes per sector 


® On floppy disks, the number of sectors per track is taken from the BIOS floppy disk 
parameter table whose address is stored in the vector for Int 1EH. 

= When this function is used for floppy disks on the PC/AT or PS/2, it should be pre- 
ceded by a call to Int 13H Function 17H to select the type of medium to be 
formatted. : 


® On fixed disks, the upper 2 bits of the 10-bit cylinder number are placed in the up- 
per 2 bits of register CL. 


IBM ROM BIOS and Mouse Functions Reference S41 


™ On PC/XT-286, PC/AT, and PS/2 fixed disks, ES:BX points to a 512-byte buffer con- 
taining byte pairs for each physical disk sector, as follows: 


Byte Contents 

0 00H for good sector 
80H for bad sector 

1 sector number 


For example, to format a track with 17 sectors and an interleave of two, ES:BX would 
point to the following 34-byte array at the beginning of a 512-byte buffer: 


db 00h,01h,00h,0ah,00h,02h,00h,0bh,00h,03h,00h, Och 

db 00h,04h,00h,0dh,00h,05h, 00h, 0eh, 00h, 06h, 00h, Ofh 

db 00h,07h,00h,10h,00h,08h,00h,11h,00h,09h 
ee 
Int 13H [PC] 
Function 06H 
Format bad track 


SSS SSS SSS eee 
Initializes a track, writing disk address fields and data sectors and setting bad sector flags. 


eee 
Call with: AH = 06H 


AL = interleave 
CH = cylinder 
DH = head 

DL = drive 


SOH-FFH fixed disk 


Returns: If function successful 
Carry flag =clear 
AH ' = (00H 
If function unsuccessful 
Carry flag = set 
AH = status (see Int 13H Function 01H) 


Notes: ™ This function is defined for PC/XT fixed disk drives only. 
® For additional information, see Notes for Int 13H Function 05H. 
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ee 


Int 13H [PC] 
Function 07H 
Format drive 


Formats the entire drive, writing disk address fields and data sectors, starting at the specified cylinder. 


ee a 


Call with: AH = 07H 
AL = interleave 
CH = cylinder 
DL = drive 


SOH-FFH fixed disk 


sa a SS SS 


Returns: If function successful 
Carry flag = clear 
AH = 0OH 


If function unsuccessful 
Carry flag =set 
AH = status (see Int 13H Function 01H) 


Notes: ™ This function is defined for PC/XT fixed disk drives only. 
® For additional information, see Notes for Int 13H Function 05H. 


ES 
Int 13H [PC] [AT] [PS/2] 
Function 08H 


Get drive parameters 


a 


Returns various parameters for the specified drive. 


ee ee ee ee ee 


Call with: AH = 08H 
DL = drive 
OOH-7FH floppy disk 
SOH-FFH fixed disk 


a ip a 


Returns: If function successful 
Carry flag = clear 
BL = drive type (PC/AT and PS/2 floppy disks) 
01H if 360 KB, 40 track, 5.25" 
02H if 1.2 MB, 80 track, 5.25" 
03H if 720 KB, 80 track, 3.5" 
04H if 1.44 MB, 80 track, 3.5" 
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CH = low 8 bits of maximum cylinder number 


CL = bits 6-7 high-order 2 bits of maximum cylinder number 
bits0-5 maximum sector number 
DH = maximum head number 
DL = number of drives 
ES:DI = segment:offset of disk drive parameter table 
If function unsuccessful 
Carry flag =set 
AH = status (see Int 13H Function 01H) 
Notes: ™ On the PC and PC/XT, this function is supported on fixed disks only. 


™ The value returned in register DL reflects the true number of physical drives at- 
tached to the adapter for the requested drive. 


$e 


Int 13H [PC] [AT] [PS/2] 
Function 09H 
Initialize fixed disk characteristics 


Initializes the fixed disk controller for subsequent I/O operations, using the values found in the ROM 
BIOS disk parameter block(s). 


Call with: AH 


= 09H 
DL = drive 
SOH-FFH fixed disk 
and, on the PC/XT 
Vector for Int 41H must point to disk parameter block 


or, on the PC/AT and PS/2 


Vector for Int 41H must point to disk parameter block for drive 0 
Vector for Int 46H must point to disk parameter block for drive 1 


Returns: If function successful 
Carry flag =clear 
AH = 00H 
If function unsuccessful 
Carry flag = set 
AH = status (see Int 13H Function 01H) 
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Notes: = This function is supported on fixed disks only. 


™ For PC and PC/XT fixed disks, the parameter block format is as follows: 
Byte(s) Contents 
OOH-01H maximum number of cylinders 
02H maximum number of heads 
03H-04H _ starting reduced write current cylinder 
05H-06H _ starting write precompensation cylinder 


07H maximum ECC burst length 
08H drive options 
Bit(s) Significance (if set) 
0-2 drive option 
3-5 reserved (0) 
6 disable ECC retries 
7 disable disk-access retries 
09H standard time-out value 
OAH time-out value for format drive 
0OBH time-out value for check drive 


OCH-—OFH _ reserved 


@ For PC/AT and PS/2 fixed disks, the parameter block format is as follows: 
Byte(s) Contents 
QOOH-01H maximum number of cylinders 
02H maximum number of heads 
03H-04H reserved 
0SH-06H _ starting write precompensation cylinder 


07H maximum ECC burst length 
08H drive options 
Bit(s) Significance (if set) 
0-2 not used 
3 more than 8 heads 
4 not used 
5 manufacturer’s defect map present at maximum 
cylinder + 1 
6-7 nonzero (10, 01, or 11) if retries disabled 


O9H-—OBH reserved 

OCH-—ODH landing zone cylinder 
OEH sectors per track 

OFH reserved 


Int 13H [PC] [AT] [PS/2] 
Function 0AH (10) 
Read sector long 


Reads a sector or sectors from disk into memory, along with a 4-byte ECC code for each sector. 
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Call with: 


AH = QAH 
AL = number of sectors 
CH = cylinder 
CL = sector (see Notes) 
DH = head 
DL = drive 
SOH-FFH fixed disk 
ES:BX = segment:offset of buffer 


__——— eee 


Returns: 


Notes: 


If function successful 
Carry flag =clear 


AH = 00H 

AL = number of sectors transferred 

If function unsuccessful 

Carry flag =set 

AH = status (see Int 13H Function 01H) 


™ This function is supported on fixed disks only. 

= The upper 2 bits of the 10-bit cylinder number are placed in the upper 2 bits of 
register CL. 

™ Unlike the normal Read Sector function (Int 13H Function 02H), ECC errors are not 


automatically corrected. Multisector transfers are terminated after any sector with a 
read error. | 


SSS SSS 


Int 13H 


[PC] [AT] [PS/2] 


Function OBH (11) 
Write sector long 


Writes a sector or sectors from memory to disk. Each sector’s worth of data must be followed by its 4-byte 


ECC code. 
Call with: AH = 0BH 
AL = number of sectors 
CH = cylinder 
CL = sector (see Notes) 
DH = head 
DL = drive 
80H-FFH fixed disk 
ES:BX = segment:offset of buffer 
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Returns: If function successful 
Carry flag =clear 
AH = 00H 
AL = number of sectors transferred 
If function unsuccessful 
Carry flag =set 
AH = status (see Int 13H Function 01H) 


Notes: ™ This function is supported on fixed disks only. 


® The upper 2 bits of the 10-bit cylinder number are placed in the upper 2 bits of 
register CL. 


a 


Int 13H [PC] [AT] [PS/2] 
Function OCH (12) 
Seek 


ee 


Positions the disk read/write heads to the specified cylinder, but does not transfer any data. 


Call with: AH = 0CH 

CH = lower 8 bits of cylinder 

CL = upper 2 bits of cylinder in bits 6-7 

DH = head 

DL = drive 

SOH-FFH fixed disk 

eae aa ee ee ee 
Returns: If function successful 

Carry flag = clear 

AH = 00H 


If function unsuccessful 

Carry flag =set 

AH = status (see Int 13H Function 01H) 
i a 
Notes: # This function is supported on fixed disks only. 


™ The upper 2 bits of the 10-bit cylinder number are placed in the upper 2 bits of 
register CL. 

™ The Read Sector, Read Sector Long, Write Sector, and Write Sector Long functions 
include an implied seek operation and need not be preceded by an explicit call to 
this function. 
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ee eee 
Int 13H [PC] [AT] [PS/2] 
Function 0DH (13) 

Reset fixed disk system 


Resets the fixed disk controller, recalibrates attached drives (moves the read/write arm to cylinder 0), and 
prepares for subsequent disk I/O. 


Call with: AH = 0DH 
DL = drive 
SOH-FFH fixed disk 


Returns: If function successful 
Carry flag =clear 
AH = 00H 


If function unsuccessful 
Carry flag = set 
AH = status (see Int 13H Function 01H) 


Note: = This function is supported on fixed disks only. It differs from Int 13H Function 00H 
in that the floppy disk controller is not reset. 


SS SSS es 
Int 13H [PC] 
Function OEH (14) 

Read sector buffer 
SSS SS : 
Transfers the contents of the fixed disk adapter’s internal sector buffer to system memory. No data is read 
from the physical disk drive. 


Call with: AH = 0EH 
ES:BX = segment:offset of buffer 


Returns: If function successful 
Carry flag =clear 


If function unsuccessful 
Carry flag = set 


AH = status (see Int 13H Function 01H) 
i 
Note: = This function is supported by the PC/XT’s fixed disk adapter only. It is not defined 


for fixed disk adapters on the PC/AT or PS/2. 
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Int 13H [PC] 
Function OFH (45) 
Write sector buffer 


Transfers data from system memory to the fixed disk adapter’s internal sector buffer. No data is written to 
the physical disk drive. 


Call with: AH = 0OFH 
ES:BX = segment:offset of buffer 
Returns: If function successful 


Carry flag =clear 

If function unsuccessful 

Carry flag =set 

AH = status (see Int 13H Function 01H) 


Notes: ™ This function is supported by the PC/XT’s fixed disk adapter only. It is not defined 
for fixed disk adapters on the PC/AT or PS/2. 
= This function should be called to initialize the contents of the sector buffer before 
formatting the drive with Int 13H Function 05H. 


Int 13H [PC] [AT] [PS/2] 
Function 10H (16) 
Get drive status 


Tests whether the specified fixed disk drive is operational and returns the drive’s status. 


Call with: AH = 10H 
DL = drive 
SOH-FFH fixed disk 
Returns: If function successful 
Carry flag =clear 
AH = 00H 


If function unsuccessful 
Carry flag = set 
AH = status (see Int 13H Function 01H) 


Note: = This function is supported on fixed disks only. 
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Int 13H [PC] [AT] [PS/2] 
Function 11H (17) 
Recalibrate drive 


Causes the fixed disk adapter to recalibrate itself for the specified drive, positioning the read/write arm to 
cylinder 0, and returns the drive’s status. 


Call with: AH =11H 
DL = drive 
SOH-FFH fixed disk 


Returns: If function successful 
Carry flag =clear 
AH = 00H 
If function unsuccessful 
Carry flag =set 


AH = status (see Int 13H Function 01H) 
Note: = This function is supported on fixed disks only. 
Int 13H [PC] 
Function 12H (18) 


Controller RAM diagnostic 


Causes the fixed disk adapter to carry out a built-in diagnostic test on its internal sector buffer, indicating 
whether the test was passed by the returned status. 


Call with: AH = 12H 


Returns: If function successful 
Carry flag =clear 
If function unsuccessful 
Carry flag =set 
AH = status (see Int 13H Function 01H) 


Note: = This function is supported on PC/XT fixed disks only. 
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Int 13H [PC] 
Function 13H (9) 
Controller drive diagnostic 


Causes the fixed disk adapter to run internal diagnostic tests of the attached drive, indicating whether the 
test was passed by the returned status. 


Call with: AH = 13H 


Returns: If function successful 
Carry flag =clear 
If function unsuccessful 
Carry flag =set 


AH = status (see Int 13H Function 01H) 
Note: ® This function is supported on PC/XT fixed disks only. 
Int 13H [PC] [AT] [PS/2] 
Function 14H (20) 


Controller internal diagnostic 


Causes the fixed disk adapter to carry out a built-in diagnostic self-test, indicating whether the test was 
passed by the returned status. 


Call with: AH = 14H 

Returns: If function successful 
Carry flag =clear 
AH = QOH 


If function unsuccessful 
Carry flag =set 
AH = status (see Int 13H Function 01H) 


Note: ™ This function is supported on fixed disks only. 
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Int 13H [AT] [PS/2] 
Function 15H (21) 


Get disk type 
Returns a code indicating the type of floppy or fixed disk referenced by the specified drive code. 
Call with: AH = 15H 
DL = drive 
OOH—7FH floppy disk 
SOH-FFH fixed disk 


Returns: | If function successful 

Carry flag =clear 

AH = drive type code 
OOH if no drive present 
O1H if floppy disk drive without change-line support 
02H if floppy disk drive with change-line support 
03H if fixed disk 

and, if fixed disk (AH = 03H) 

CX:DX = number of 512-byte sectors 

If function unsuccessful 

Carry flag = set 

AH = status (see Int 13H Function 01H) 


Note: = This function is not supported on the PC or PC/XT. 


Int 13H [AT] [PS/2] 
Function 16H (22) 
Get disk change status 


Returns the status of the change line, indicating whether the disk in the drive may have been replaced 
since the last disk access. 


Call with: AH = 16H 
DL = drive 
OOH—7FH floppy disk 
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Returns: If change line inactive (disk has not been changed) 
Carry flag = clear 
AH = 00H 
If change line active (disk may have been changed) 
Carry flag =set 
AH = 06H 


Notes: = If this function returns with the carry flag set, the disk has not necessarily been 
changed; the change line can be activated by simply unlocking and locking the disk 
drive door without removing the floppy disk. 


= This function is not supported for floppy disks on the PC or PC/XT. 


Int 13H [AT] [PS/2] 
Function 17H (23) 
Set disk type 


Selects a floppy disk type for the specified drive. 


Call with: AH = 17H 

AL = floppy disk type code 
OOH not used 
O1H 320/360 KB floppy disk in 360 KB drive 
02H 320/360 KB floppy disk in 1.2 MB drive 
03H 1.2 MB floppy disk in 1.2 MB drive 
04H 720 KB floppy disk in 720 KB drive 

SL = drive 
OOH—7FH floppy disk 


Returns: If function successful 
Carry flag =clear 
AH = 00H 


If function unsuccessful 
Carry flag =set 
AH = status (see Int 13H Function 01H) 


Notes: = This function is not supported for floppy disks on the PC or PC/XT. 


m Ifthe change line is active for the specified drive, it is reset. The ROM BIOS then sets 
the data rate for the specified drive and media type. 
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Int 13H [AT] [PS/2] 
Function 18H (24) 
Set media type for format 


Selects media characteristics for the specified drive. 


Call with: AH = 18H 
CH = number of cylinders 
CL = sectors per track 
DL = drive 


OOH-7FH floppy disk 


Returns: If function successful 
Carry flag = clear 
AH = OOH 
ES:DI = segment:offset of disk parameter table for media type 
If function unsuccessful 
Carry flag =set 
AH = status (see Int 13H Function 01H) 


Notes: a A floppy disk must be present in the drive. 


m This function should be called prior to formatting a disk with Int 13H Function 05H 
so that the ROM BIOS can set the correct data rate for the media. 


m Ifthe change line is active for the specified drive, it is reset. 


Int 13H [PS/2] 
Function 19H (25) 
Park heads 


Moves the read/write arm to a track that is not used for data storage, so that data will not be damaged 
when the drive is turned off. 


Call with: AH = 19H 
DL = drive 
SOH-FFH fixed disk 
Returns: If function successful 
Carry flag =clear 
AH = 00H 
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If function unsuccessful 
Carry flag =set 
AH = status (see Int 13H Function 01H) 


Note: 


a This function is defined for PS/2 fixed disks only. 


Int 15H 


Function 1AH (26) 
Format ESDI drive 


[PS/2] 


Initializes disk sector and track address fields on a drive attached to the ESDI Fixed Disk Drive Adapter/A. 


Call with: 


AH = 1AH 


Returns: 


Notes: 


AL = relative block address (RBA) defect table count 
0 if no RBA table 
>0 if RBA table used 
CL = format modifier bits 
Bit(s) Significance (if set) 
0 ignore primary defect map 
1 ignore secondary defect map 
2 update secondary defect map (see Notes) 
3 perform extended surface analysis 
4 generate periodic interrupt (see Notes) 
5-7 reserved (must be 0) 
DL = drive 
SOH-FFH fixed disk 
ES:BX = segment:offset of RBA table 


If function successful 

Carry flag =clear 

AH = 00H 

If function unsuccessful 

Carry flag =set 

AH = status (see Int 13H Function 01H) 


= This operation is sometimes called a “low level format” and prepares the disk for 
physical read/write operations at the sector level. The drive must be subsequently 
partitioned with the FDISK command and then given a “high level format” with the 


FORMAT command to install a file system. 
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= If bit 4 of register CL is set, Int 15H is called with AH = OFH and AL = phase code 
after each cylinder is formatted or analyzed. The phase code is defined as: 
0 = reserved 
1 = surface analysis 
2 = formatting 
See also Int 15H Function OFH. 
m= If bit 2 of register CL is set, the drive’s secondary defect map is updated to reflect er- 
rors found during surface analysis. If both bit 2 and bit 1 are set, the secondary defect 
map is replaced. 
m Foran extended surface analysis, the disk should first be formatted by calling this 
function with bit 3 cleared, then analyzed by calling this function with bit 3 set. 


Int 14H [PC] [AT] [PS/2] 
Function 00H 
Initialize communications port 


Initializes a serial communications port to a desired baud rate, parity, word length, and number of 
stop bits. 


Call with: AH = 00H 
AL = initialization parameter (see Notes) 
DX = communications port number (0 = COM1, 1 = COM2, etc.) 
Returns: AH = port status 

Bit Significance (if set) 
0 receive data ready 
1 overrun error detected 
2 parity error detected 
3 framing error detected 
4 break detected 
5 transmit holding register empty 
6 transmit shift register empty 
7 timed-out 

AL = modem status 
Bit Significance (if set) 
0 change in clear-to-send status 
1 change in data-set-ready status 
2 trailing edge ring indicator 
3 change in receive line signal detect 
4 clear-to-send 
5 data-set-ready 
6 ring indicator 
il receive line signal detect 
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Notes: 


w The initialization parameter byte is defined as follows: 


765 43 2 10 

Baud rate Parity Stop bits Word length 
000 = 110 XO = none 0 = 1 bit 10 = 7 bits 
001 = 150 01 = odd 1 = 2 bits 11 = 8 bits 
010 = 300 11 = even 

011 = 600 

100 = 1200 

101 = 2400 

110 = 4800 

111 = 9600 


a To initialize the serial port for data rates greater than 9600 baud on PS/2 machines, 


see Int 14H Functions 04H and 05H. 


Int 14H 


[PC] [AT] [PS/2] 


Function 01H 
Write character to communications port 


Writes a character to the specified serial communications port, returning the current status of the port. 


Call with: 


Returns: 


AH = 01H 
AL = character 
DX = communications port number (0 = COM1, 1 = COM2, etc.) 


If function successful 


AH bit 7 =( 
AH bits 0-6 = port status 
Bit Significance (if set) 
0 receive data ready 
1 overrun error detected 
2 parity error detected 
3 framing error detected 
4 break detected 
5 transmit holding register empty 
6 transmit shift register empty 
AL = character (unchanged) 
If function unsuccessful (timed-out) 
AH bit 7 =] 
AL = character (unchanged) 
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Int 14H [PC] [AT] [PS/2] 
Function 02H 
Read character from communications port 


Reads a character from the specified serial communications port, also returning the port’s status. 


Call with: AH = 02H 
DX = communications port number (0 = COM1, 1 = COM2, etc.) 
Returns: If function successful 
AH bit 7 = (0 
AH bits 0-6 = status 
Bit Significance (if set) 
1 overrun error detected 
2 parity error detected 
3 framing error detected 
4 break detected 
AL = character 
If function unsuccessful (timed-out) 
AH bit 7 =] 
Int 14H [PC] [AT] [PS/2] 
Function 03H 


Get communications port status 


Returns the status of the specified serial communications port. 


Call with: AH = 03H 
DX = communications port number (0 = COM1, 1 = COM2, etc.) 
Returns: AH = port status (see Int 14H Function 00H) 
AL = modem status (see Int 14H Function 00H) 
Int 14H [PS/2] 
Function 04H 


Extended initialize communications port 


Initializes a serial communications port to a desired baud rate, parity, word length, and number of stop 
bits. Provides a superset of Int 14H Function 00H capabilities for PS/2 machines. 
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Call with: AH = 04H 


AL = break flag 
OOH no break 
O1H break 
BH = parity 
OOH none 
O1H odd 
02H even 


03H stick parity odd 
04H stick parity even 
BL = stop bits 
OOH 1 stop bit 
01H 2 stop bits if word length = 6-8 bits 
01H 1.5 stop bits if word length = 5 bits 


CH = word length 
OOH 5 bits 
O1H 6 bits 
02H 7 bits 
03H 8 bits 
CL = baud rate 


OOH 110 baud 
01H 150 baud 
02H 300 baud 
03H 600 baud 
04H 1200 baud 
05H 2400 baud 
O6H 4800 baud 
O7H 9600 baud 
O8H 19,200 baud 


DX = communications port number (0 = COM1, 1 = COM2, etc.) 
Returns: AH = port status (see Int 14H Function 00H) 

AL = modem status (see Int 14H Function 00H) 
Int 14H [PS/2] 
Function 05H 


Extended communications port control 


Reads or sets the modem control register (MCR) for the specified serial communications port. 


Call with: AH = 05H 
AL = subfunction 
OOH to read modem control register 
O1H to write modem control register 
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BL = modem control register contents Cif AL = 01H) 
Bit(s) Significance 


0 data-terminal ready 
1 request-to-send 
2 Outl 
3 Out2 
4 loop (for testing) 
5-7 reserved 
DX = communications port number (0 = COM1, 1 = COM2, etc.) 
Returns: If called with AL = 00H 
BL = modem control register contents (see above) 
If called with AL = 01H 
AH = port status (see Int 14H Function 00H) 
AL = modem status (see Int 14H Function 00H) 
Int 15H [PC] 
Function 00H 


Turn on cassette motor 


Turns on the motor of the cassette tape drive. 


Call with: AH = 00H 


Returns: If function successful 
Carry flag =clear 


If function unsuccessful 
Carry flag =set 


AH = status 
86H if cassette not present 
Note: m This function is available only on the PC and the PCjr. It is not supported on the 


PC/XT and all subsequent models. 


Int 15H [PC] 
Function 01H 


Turn off cassette motor 


Turns off the motor of the cassette tape drive. 
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Call with: AH = 01H 


Returns: - If function successful 
Carry flag = clear 
If function unsuccessful 
Carry flag =set 


AH = status 
80H if cassette not present 
Note: ™ This function is available only on the PC and the PCjr. It is not supported on the 


PC/XT and all subsequent models. 


Int 15H [PC] 
Function 02H 
Read cassette 


Reads one or more 256-byte blocks of data from the cassette tape drive to memory. 


Call with: AH = 02H 
CX = number of bytes to read 
ES:BX = segment:offset of buffer 
Returns: If function successful 
Carry flag =clear 
DX = number of bytes actually read 
ES:BX = segment:offset + 1 of last byte read 


If function unsuccessful 

Carry flag =set 

AH = status 
01H if CRC error 
02H if bit signals scrambled 
04H if no data found 
80H if invalid command 
86H if cassette not present 


Note: = This function is available only on the PC and on the PCjr. It is not supported on the 
PC/XT and all subsequent models. 


IBM ROM BIOS and Mouse Functions Reference S61 


Int 15H [PC] 
Function 03H 
Write cassette 


Writes one or more 256-byte blocks of data from memory to the cassette tape drive. 


Callwith: AH = 03H 
CX = number of bytes to write 
ES:BX = segment:offset of buffer 


Returns: If function successful 
Carry flag =clear 
CX = 00H 
ES:BX = segment:offset + 1 of last byte written 
If function unsuccessful 
Carry flag =set 


AH = status 
SOH if invalid command 
86H if cassette not present 
Note: ™ This function is available only on the PC and on the PCjr. It is not supported on the 


PC/XT and all subsequent models. 


Int 15H | [PS/2] 
Function OFH (15) 
Format ESDI drive periodic interrupt 


Invoked by the ROM BIOS on the ESDI Fixed Disk Drive Adapter/A during a format or surface analysis 
operation after each cylinder is completed. 


Call with: AH = OFH 
AL = phase code 
O = reserved 


1 = surface analysis 
2 = formatting 


Returns: If formatting or analysis should continue 
Carry flag =clear 


If formatting or analysis should be terminated 
Carry flag = set 
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Notes: = This function call can be captured by a program so that it will be notified as each 
cylinder is formatted or analyzed. The program can count interrupts for each phase 
to determine the current cylinder number. 


= The default ROM BIOS handler for this function returns with the carry flag set. 


Int 15H [PS/2] 
Function 21H (33) Subfunction 00H 
Read POST error log 


Returns error information that was accumulated during the most recent power-on self-test (POST). 


Call with: AH = 21H 
AL = 00H 
Returns: If function successful 
Carry flag =clear 
AH = 00H 
BX = number of POST error codes stored 
ES:DI = segment:offset of POST error log 


If function unsuccessful 
Carry flag =set 


AH = status 
8OH = invalid command 
86H = function not supported 
Notes: w The error log consists of single-word entries. The first byte of an entry is the device 


error code, and the second is the device identifier. 
s This function is not available on the PS/2 Models 25 and 30. 


Int 15H [PS/2] 
Function 21H (33) Subfunction 01H 
Write POST error log 


a 


Adds an entry to the power-on self-test (POST) error log. 


Call with: AH = 21H 
AL = 01H 
BH = device identifier 
BL = device error code 
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_— Or eee 


Returns: If function successful 
Carry flag =clear 
AH = 00H 
If function unsuccessful 
Carry flag =set 


AH = status 
01H = error list full 
SOH = invalid command 
86H = function not supported 
Note: = This function is not available on the PS/2 Models 25 and 30. 


————— 
Int 15H [PS/2] 


Function 4FH (79) 
Keyboard intercept 


Invoked for each keystroke by the ROM BIOS’s Int 09H keyboard interrupt handler. 


Call with: AH = 4FH 


AL = scan code 


Returns: If scan code consumed 
Carry flag =clear 


If scan code not consumed 
Carry flag = set 


AL = unchanged or new scan code 
5 ss ss 
Notes: ™ An operating system or a resident utility can capture this function to filter the raw 


keyboard data stream. The new handler can substitute a new scan code, return the 
same scan code, or return the carry flag clear causing the keystroke to be discarded. 
The default ROM BIOS routine simply returns the scan code unchanged. 


= A program can call Int 15H Function COH to determine whether the host machine’s 
ROM BIOS supports this keyboard intercept. 


Int 15H [AT] [PS/2] 
Function 80H (128) 
Device open 


Acquires ownership of a logical device for a process. 
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Call with: AH = 80H 


BX = device ID 

CX = process ID 
Returns: If function successful 

Carry flag = clear 

AH = 0OH 


If function unsuccessful 
Carry flag =set 
AH = status 


Note: ® This function call, along with Int 15H Functions 81H and 82H, defines a simple pro- 
tocol that can be used to arbitrate usage of devices by multiple processes. A multi- 
tasking program manager would be expected to capture Int 15H and provide the 
appropriate service. The default BIOS routine for this function simply returns with 
the carry flag clear and AH = 00H. 


Int 15H | [AT] [PS/2] 
Function 81H (129) 
Device close 


Releases ownership of a logical device for a process. 


Call with: AH = 81H 
BX = device ID 
CX = process ID 
Returns: If function successful 
Carry flag =clear 
AH = QOH 


If function unsuccessful 
Carry flag =set 
AH = status 


Note: = A multitasking program manager would be expected to capture Int 15H and provide 
the appropriate service. The default BIOS routine for this function simply returns 
with the carry flag clear and AH = OOH. See also Int 15H Functions 80H and 82H. 
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Int 15H [AT] [PS/2] 
Function 82H (130) 
Process termination 


Releases ownership of all logical devices for a process that is about to terminate. 


Callwith: AH = 82H 
BX = process ID 


Returns: If function successful 
Carry flag =clear 
AH = 00H 
If function unsuccessful 
Carry flag =set 
AH = status 


Note: = A multitasking program manager would be expected to capture Int 15H and provide 
the appropriate service. The default BIOS routine for this function simply returns 
with the carry flag clear and AH = OOH. See also Int 15H Functions 80H and 81H. 


Int 15H [AT] [PS/2] 
Function 83H (131) 
Event wait 


Requests setting of a semaphore after a specified interval or cancels a previous request. 


Call with: —_ If requesting event wait 


AH = 83H 

AL = 00H 

CX:DX = microseconds 

ES:BX = segment:offset of semaphore byte 
If canceling event wait 

AH = 83H 

AL = 01H 


SSeS 
Returns: If called with AL = 00H, and function successful 


Carry flag =clear 

If called with AL = 00H, and function unsuccessful (Event Wait already active) 
Carry flag = set 

If called with AL = 01H 

Nothing 
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Notes: = The function call returns immediately. If the function is successful, bit 7 of the sema- 
phore byte is set when the specified interval has elapsed. The calling program is 
responsible for clearing the semaphore before requesting this function. 


m= The actual duration of an event wait is always an integral multiple of 976 microsec- 
onds. The CMOS date/clock chip interrupts are used to implement this function. 

= Use of this function allows programmed, hardware-independent delays at a finer 
resolution than can be obtained through use of the MS-DOS Get Time function (int 
21H Function 2CH, which returns time in hundredths of a second). 

= See also Int 15H Function 86H, which suspends the calling program for the specified 
interval in milliseconds. 


= This function is not supported on the PS/2 Models 25 and 30. 


Int 15H [AT] [PS/2] 
Function 84H (132) 
Read joystick 


Returns the joystick switch settings and potentiometer values. 


Call with: AH = 84H 
DX = subfunction 
OOH to read switch settings 
01H to read resistive inputs 


Returns: If function successful 
Carry flag =clear 


and, if called with DX = 00H 


AL = switch settings (bits 4-7) 
or, if called with DX = 01H 

AX = A(x) value 

BX = A(y) value 

CX = B(x) value 

DX = B(y) value 


If function unsuccessful 
Carry flag =set 


Notes: m Anerror condition is returned if DX does not contain a valid subfunction number. 


= If no game adapter is installed, AL is returned as 00H for Subfunction 00H (i.e., 
all switches open); AX, BX, CX, and DX are returned containing 00H for Subfunc- 
tion 01H. 


@ Using a 250 KOhm joystick, the potentiometer values usually lie within the 
range 0—416 (0000-—01A0H). 


IBM ROM BIOS and Mouse Functions Reference S67 


Int 15H [AT] [PS/2] 
Function 85H (133) 
SysReq key 


Invoked by the ROM BIOS keyboard driver when the SysReq key is detected. 


Call with: AH = 85H 
AL = key status 
OOH if key make (depression) 
O1H if key break (release) 


Returns: If function successful 
Carry flag =clear 
AH = 00H 
If function unsuccessful 
Carry flag = set 
AH = status 


Note: = The ROM BIOS handler for this function call is a dummy routine that always returns 
a success status unless called with an invalid subfunction number in AL. A multitask- 
ing program manager would be expected to capture Int 15H so that it can be 
notified when the user strikes the SysReq key. 


Int 15H [AT] [PS/2] 
Function 86H (134) 
Delay 


Suspends the calling program for a specified interval in microseconds. 


Call with: AH = 86H 
CX:DX = microseconds to wait 
Returns: If function successful (wait was performed) 


Carry flag =clear 


If function unsuccessful (wait was not performed) 
Carry flag = set 


Notes: = The actual duration of the wait is always an integral multiple of 976 microseconds. 


Use of this function allows programmed, hardware-independent delays at a finer 
resolution than can be obtained through use of the MS-DOS Get Time function 
(Int 21H Function 2CH, which returns time in hundredths of a second). 
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= See also Int 15H Function 83H, which triggers a semaphore after a specified interval 
but does not suspend the calling program. 


Int 15H [AT] [PS/2] 
Function 87H (135) 
Move extended memory block 


Transfers data between conventional memory and extended memory. 


Call with: AH = 87H 

CX = number of words to move 

ES:SI = segment:offset of Global Descriptor Table (see Notes) 
Returns: If function successful 

Carry flag =clear 

AH = 00H 


If function unsuccessful 
Carry flag =set 


AH = status 
01H if RAM parity error 
02H if exception interrupt error 


03H if gate address line 20 failed 


a 


Notes: = Conventional memory lies at addresses below the 640 KB boundary, and is used for 
the execution of MS-DOS and its application programs. Extended memory lies at ad- 
dresses above 1 MB, and can only be accessed by an 80286 or 80386 CPU running in 
protected mode. As much as 15 MB of extended memory can be installed in an IBM 
PC/AT or compatible. 


mw The Global Descriptor Table (GDT) used by this function must be set up as follows: 
Byte(s) Contents 
OOH-—OFH reserved (should be 0) 
10H-11H segment length in bytes (2*CX — 1 or greater) 
12H-14H 24-bit source address 
15H access rights byte (always 93H) 
16H-17H _ reserved (should be 0) 
18H-19H segment length in bytes (2*CX — 1 or greater) 
1AH-1CH 24-bit destination address 
1DH access rights byte (always 93H) 
1EH-—2FH reserved (should be 0) 


The table is composed of six 8-byte descriptors to be used by the CPU in protected 
mode. The four descriptors in offsets OOH-OFH and 20H-2FH are filled in by the 
ROM BIOS before the CPU mode switch. 
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™ The addresses used in the descriptor table are linear (physical) 24-bit addresses in 
the range 000000H-FFFFFFH—not segments and offsets—with the least significant 
byte at the lowest address and the most significant byte at the highest address. 

@ The block move is performed with interrupts disabled; thus, use of this function may 
interfere with the operation of communications programs, network drivers, or other 
software that relies on prompt servicing of hardware interrupts. 

™ Programs and drivers that access extended memory with this function cannot be 
executed in the Compatibility Environment of OS/2. 

@ This function is not supported on the PS/2 Models 25 and 30. 


Int 15H [AT] [PS/2] 
Function 88H (136) 
Get extended memory size 


Returns the amount of extended memory installed in the system. 


Call with: AH = 88H 
Returns: AX = amount of extended memory (in KB) 
Notes: | = Extended memory is memory at addresses above 1 MB, which can only be accessed 


by an 80286 or 80386 CPU running in protected mode. Because MS-DOS is a real- 
mode operating system, extended memory can be used for storage of volatile data 
but cannot be used for execution of programs. 

= Programs and drivers that use this function cannot be executed in the Compatibility 
Environment of OS/2. 


® This function is not supported on the PS/2 Models 25 and 30. 


Int 15H [AT] [PS/2] 
Function 89H (137) 
Enter protected mode 


Switches the CPU from real mode into protected mode. 


Call with: AH = 89H 
BH = interrupt number for IRQO, written to ICW2 of 8259 PIC #1 (must be 
evenly divisible by 8, determines IRQO-IRQ7) 
BL = interrupt number for IRQ8, written to ICW2 of 8259 PIC #2 (must be 
evenly divisible by 8, determines IRQ8-IRQ15) 
ES:SI = segment:offset of Global Descriptor Table (GDT) 
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rr 


Returns: If function successful (CPU is in protected mode) 
Carry flag =clear 


AH = 00H 

CS = user-defined selector 
DS = user-defined selector 
ES = user-defined selector 
SS = user-defined selector 


If function unsuccessful (CPU is in real mode) 
Carry flag =set 
AH = FFH 


Notes: = The Global Descriptor Table must contain eight descriptors set up as follows: 
Offset Descriptor usage 
00H dummy descriptor (initialized to 0) 
08H Global Descriptor Table (GDT) 
10H Interrupt Descriptor Table (DT) 
18H user’s data segment (DS) 
20H user’s extra segment (ES) 
28H user’s stack segment (SS) 
30H user’s code segment (CS) 
38H BIOS code segment 


The user must initialize the first seven descriptors; the eighth is filled in by the ROM 
BIOS to provide addressability for its own execution. The calling program may modi- 
fy and use the eighth descriptor for any purpose after return from this function call. 


= This function is not supported on the PS/2 Models 25 and 30. 


en 


Int 15H [AT] [PS/2] 
Function 90H (144) 
Device wait 


nD 


Invoked by the ROM BIOS fixed disk, floppy disk, printer, network, and keyboard drivers prior to per- 
forming a programmed wait for I/O completion. 


Call with: AH = 90H 
AL = device type 
OOH-7FH _ serially reusable devices 
SOH-BFH _ reentrant devices 
COH-FFH wait-only calls, no corresponding Post function 
ES:BX = segment:offset of request block for device types 830H—-FFH 
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Returns: If no wait (driver must perform its own time-out) 
Carry flag =clear 
AH = 00H 


If wait was performed 
Carry flag = set 


CC O erOwmWUO SESS 


Notes: m Predefined device types are: 


00H disk (may time-out) 

01H floppy disk (may time-out) 

02H keyboard (no time-out) E 

03H pointing device (PS/2, may time-out) 

80H network (no time-out) 

FCH fixed disk reset (PS/2, may time-out) 

FDH floppy disk drive motor start (may time-out) 
FEH printer (may time-out) 


w For network adapters, ES:BX points to a network control block (NCB). 


= A multitasking program manager would be expected to capture Int 15H Function 
90H so that it can dispatch other tasks while I/O is in progress. The default BIOS 
routine for this function simply returns with the carry flag clear and AH = 00H. 


Int 15H [AT] [PS/2] 


Function 91H (145) 
Device post 


ee 
Invoked by the ROM BIOS fixed disk, floppy disk, network, and keyboard drivers to signal that I/O is 
complete and/or the device is ready. 


a = 
Call with: AH = 91H 


AL = device type 
OOH—7FH _ serially reusable devices 
SOH-BFH reentrant devices 
ES:BX = segment:offset of request block for device types 80H-BFH 


Returns: AH = 00H 


Notes: m Predefined device types that may use Device Post are: 
00H disk (may time-out) 
01H floppy disk (may time-out) 
02H keyboard (no time-out) 
03H pointing device (PS/2, may time-out) 
80H network (no time-out) 
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= The ROM BIOS printer routine does not invoke this function because printer output 
is not interrupt driven. 


= A multitasking program manager would be expected to capture Int 15H Function 
91H so that it can be notified when I/O is completed and awaken the requesting 
task. The default BIOS routine for this function simply returns with the carry flag 
clear and AH = 00H. 


a SS 


Int 15H [AT] [PS/2] 
Function COH (192) 
Get system environment 


a 


Returns a pointer to a table containing various information about the system configuration. 


Call with: AH = COH 
Returns: ES:BX = segment:offset of configuration table (see Notes) 
Notes: = The format of the system configuration table is as follows: 


Byte(s) Contents 
OOH-01H length of table in bytes 


02H system model (see following Note) 

03H system submodel (see following Note) 

04H BIOS revision level 

05H configuration flags 
Bit Significance (if set) 
0 reserved 
1 Micro Channel implemented 
2 extended BIOS data area allocated 
3 Wait for External Event is available 
4 keyboard intercept (Int 15H Function 4FH) available 
5 real-time clock available 
6 slave 8259 present (cascaded IRQ2) 
7 DMA channel 3 used 


Q06H-09H reserved 
m The system model and type bytes are assigned as follows: 


Machine Model byte Submodel byte 
PC FFH 

PC/XT FEH 

PC/XT FBH 00H or 01H 
PCjr FDH 

PC/AT FCH OOH or 01H 
PC/XT-286 FCH 02H 


PC Convertible FOH 


IBM ROM BIOS and Mouse Functions Reference S73 


Machine Model byte Submodel byte 


PS/2 Model 30 FAH OOH 

PS/2 Model 50 FCH 04H 

PS/2 Model 60 FCH 05H 

PS/2 Model 70 F8H 04H or 09H 

PS/2 Model 80 F8H OOH or 01H 
NN 
Int 15H [PS/2] 
Function C1H (193) 


Get address of extended BIOS data area 
a, 


Returns the segment address of the base of the extended BIOS data area. 


Call with: AH =C1H 


Returns: If function successful 
Carry flag =clear 
ES = segment of extended BIOS data area 
If function unsuccessful 
Carry flag =set 


Notes: = The extended BIOS data area is allocated at the high end of conventional memory 
during the POST (Power-On-Self-Test) sequence. The word at 0040:0013H (memory 
size) is updated to reflect the reduced amount of memory available for MS-DOS and 
application programs. The first byte in the extended BIOS data area is initialized to 


its length in KB. 
= A program can determine whether the extended BIOS data area exists with Int 15H 
Function COH. 
a ee 
Int 15H | [PS/2] 


Function C2H (194) Subfunction 00H 


Enable/disable pointing device 
cae a ee ee 


Enables or disables the system’s mouse or other pointing device. 


Call with: AH = C2H 
AL = 00H 
BH = enable/disable flag 
OOH = disable 


O1H = enable 
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Returns: If function successful 

Carry flag =clear 

AH = 00H 

If function unsuccessful 

Carry flag =set 

AH = status 
01H if invalid function call 
02H if invalid input 
03H if interface error 
04H if resend 
05H if no far call installed 


a SS 


Int 15H [PS/2] 
Function C2H (194) Subfunction 01H 
Reset pointing device 


Resets the system’s mouse or other pointing device, setting the sample rate, resolution, and other charac- 
teristics to their default values. 


NN IIs 


Call with: AH = C2H 

AL = 01H 
NS 
Returns: If function successful 

Carry flag =clear 

AH = 00H 

BH = device ID 


If function unsuccessful 
Carry flag =set 
AH = status (see Int 15H Function C2H Subfunction 00H) 


I 
Notes: = After a reset operation, the state of the pointing device is as follows: 

— disabled, 

— sample rate at 100 reports per second; 

— resolution at 4 counts per millimeter, 

— and scaling at 1 tol. 

The data package size is unchanged by this function. 

m The application can use the other Int 15H Function C2H subfunctions to initialize 
the pointing device to other sample rates, resolution, and scaling, and then enable 
the device with Int 15H Function C2H Subfunction 00H. 


= See also Int 15H Function C2H Subfunction 05H, which incidentally resets the point- 
ing device in a similar manner. 
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Int 15H [PS/2] 
Function C2H (194) Subfunction 02H 

Set sample rate 


Sets the sampling rate of the system’s mouse or other pointing device. 


eee 


Call with: AH = C2H 


AL = 02H 

BH = sample rate value 
OOH = 10 reports per second 
O1H = 20 reports per second 
02H = 40 reports per second 
03H = 60 reports per second 
04H = 80 reports per second 
05H = 100 reports per second 
OOH = 200 reports per second 


Returns: If function successful 
Carry flag =clear 
AH = 00H 
If function unsuccessful 
Carry flag = set 
AH = status (see Int 15H Function C2H Subfunction 00H) 


Note: = The default sample rate is 100 reports per second after a reset operation (Int 15H 
Function C2H Subfunction 01H). 


SSS aS ase ssssssssesseessssserss 


Int 15H [PS/2] 
Function C2H (194) Subfunction 03H 
Set resolution 


Sets the resolution of the system’s mouse or other pointing device. 


i 8 es es 


Call with: AH = C2H 


AL = 03H 

BH = resolution value 
OOH = 1 count per millimeter 
01H = 2 counts per millimeter 
02H = 4 counts per millimeter 
03H = & counts per millimeter 
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Returns: If function successful 
Carry flag =clear 
AH = 00H 
If function unsuccessful 
Carry flag = set 
AH = status (see Int 15H Function C2H Subfunction 00H) 


Note: = The default resolution is 4 counts per millimeter after a reset operation (Int 15H 
Function C2H Subfunction 01H). 


Int 15H [PS/2] 
Function C2H (194) Subfunction 04H 
Get pointing device type 
Returns the identification code for the system’s mouse or other pointing device. 
Call with: AH = C2H 
AL = 04H 


Returns: If function successful 
Carry flag = clear 
AH = 00H 
BH = device ID 


If function unsuccessful 
Carry flag =set 
AH = status (see Int 15H Function C2H Subfunction 00H) 


Int 15H. [PS/2] 
Function C2H (194) Subfunction 05H 
Initialize pointing device interface 


Sets the data package size for the system’s mouse or other pointing device, and initializes the resolution, 
sampling rate, and scaling to their default values. 


Call with: AH = C2H 
AL = 05H 
BH = data package size in bytes (1-8) 
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Returns: If function successful 
Carry flag =clear 
AH = 00H 


If function unsuccessful 
Carry flag = set 


AH = status (see Int 15H Function C2H Subfunction 00H) 
eee 
Note: m After this operation, the state of the pointing device is as follows: 

— disabled; 


— sample rate at 100 reports per second; 
— resolution at 4 counts per millimeter; 
and scaling at 1 to 1. 


a 
Int 15H [PS/2] 


Function C2H (194) Subfunction 06H 


Set scaling or get status 
Se 


Returns the current status of the system’s mouse or other pointing device or sets the device’s scaling 
factor. 


eee 
Call with: AH = C2H 


AL = 06H 

BH = extended command 
OOH = return device status 
01H = set scaling at 1:1 
02H = set scaling at 2:1 


Returns: If function successful 
Carry flag =clear 


AH = 00H 
and, if called with BH = 00H 
BL = status byte 
Bit Significance 
0 = 1 if right button pressed 
1 = reserved 
2 = 1 if left button pressed 
3 = reserved 
4 = 0 if 1:1 scaling 
1 if 2:1 scaling 
5 = 0 if device disabled 
1 if device enabled 
6 = 0 if stream mode 
1 if remote mode 
7 = reserved 
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CL = resolution 


OOH = 1 count per millimeter 
01H = 2 counts per millimeter 
02H = 4 counts per millimeter 
03H = 8 counts per millimeter 
DL = sample rate 

OAH = 10 reports per second 
14H = 20 reports per second 
28H = 40 reports per second 
3CH = 60 reports per second 
50H = 80 reports per second 
64H = 100 reports per second 
C8H = 200 reports per second 


If function unsuccessful 
Carry flag =set 
AH = status (see Int 15H Function C2H Subfunction 00H) 


2 


Int 15H [PS/2] 
Function C2H (194) Subfunction 07H 
Set pointing device handler address 


a Se 


Notifies the ROM BIOS pointing device driver of the address for a routine to be called each time pointing 
device data is available. 


Call with: AH = C2H 

AL = 07H 

ES:BX = segment:offset of user routine 
Returns: If function successful 


Carry flag =clear 


If function unsuccessful 
Carry flag =set 
AH = status (see Int 15H Function C2H Subfunction 00H) 


————————————— 


Notes: ® The user’s handler for pointing device data is entered via a far call with four parame- 
ters on the stack: 
SS:SP+0OAH status 
SS:SP+08H <x coordinate 
SS:SP+06H y coordinate 
SS:SP+04H 2 coordinate (always 0) 


The handler must exit via a far return without removing the parameters from 
the stack. 
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= The status parameter passed to the user’s handler is interpreted as follows: 


Bit(s) Significance (if set) 


0 left button pressed 

1 right button pressed 

2-3 reserved 

4 sign of x data is negative 
5 sign of data is negative 
6 x data has overflowed 

7 y data has overflowed 
8-15 reserved 


a 
Int 15H [PS/2] 


Function C3H (195) 
Set watchdog time-out 


Enables or disables a watchdog timer. 


OOo eee 


Call with: AH = C3H 


AL = subfunction 
OOH to disable watchdog time-out 
O1H to enable watchdog time-out 
BX = watchdog timer counter (if AL = 01H) 


Returns: If function successful 
Carry flag =clear 


If function unsuccessful 
Carry flag = set 


Notes: m The watchdog timer generates an NMI interrupt. 
w This function is not available on the PS/2 Models 25 and 30. 


a 
Int 15H [PS/2] 


Function C4H (196) 
Programmable option select 


Returns the base Programmable Option Select register address, enables a slot for setup, or enables an 
adapter. 
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Call with: AH = C4H 
AL = subfunction 
OOH to return base POS adapter register address 
01H to enable slot 
02H to enable adapter 
BL = slot number (if AL = 01H) 


Returns: If function successful 
Carry flag =clear 
and, if called with AL = 00H 
DX = base POS adapter register address 
If function unsuccessful 
Carry flag =set 


Notes: ‘a This function is available only on machines using the Micro Channel Architecture 
(MCA) bus. 
= After a slot is enabled with Subfunction 01H, specific information can be obtained 
for the adapter in that slot by performing port input operations: 


Port Function 
100H MCA ID Clow byte) 
101H MCA ID (high byte) 
102H Option Select Byte 1 
bit 0 = 1 if enabled, = 0 if disabled 
103H Option Select Byte 2 
104H Option Select Byte 3 
105H Option Select Byte 4 
bits 6-7 = channel check indicators 
106H Subaddress Extension (low byte) 
107H Subaddress Extension (high byte) 
Int 16H [PC] [AT] [PS/2] 
Function 00H 
Read character from keyboard 
Reads a character from the keyboard, also returning the keyboard scan code. 
Call with: AH = 00H 
Returns: AH = keyboard scan code 
AL = ASCII character 
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Int 16H [PC] [AT] [PS/2] 
Function 01H 
Get keyboard status 


Determines whether a character is ready for input, returning a flag and also the character itself, if one 
iS waiting. 


Call with: AH = 01H 


Returns: If key waiting to be input 


Zero flag =clear 
AH = keyboard scan code 
AL = character 
If no key waiting 
Zero flag = set 
Note: = The character returned by this function when the zero flag is clear is not removed 


from the type-ahead buffer. The same character and scan code will be returned by 
the next call to Int 16H Function 00H. 


Int 16H [PC] [AT] [PS/2] 
Function 02H 
Get keyboard flags 


Returns the ROM BIOS flags byte that describes the state of the various keyboard toggles and shift keys. 


Call with: AH = 02H 

Returns: AL = flags 
Bit Significance (if set) 
0 right Shift key is down 
1 left Shift key is down 
2 Ctrl key is down 
3 Alt key is down 
4 Scroll Lock on 
5 Num Lock on 
6 Caps Lock on 
7 Insert on 

Note: = The keyboard flags byte is stored in the ROM BIOS data area at 0000:0417H. 
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Int 16H [PC] [AT] [PS/2] 
Function 03H 
Set repeat rate 


Sets the ROM BIOS key repeat (“typematic”) rate and delay. 


Call with: |= Onthe PC/AT and PS/2 


AH = 03H 

AL = 05H 

BH = repeat delay (see Notes) 

BL = repeat rate (see Notes) 

On the PCjr 

AH = 03H 

AL = subfunction 
OOH to restore default rate and delay 
01H to increase initial delay 
02H to decrease repeat rate by one-half 
03H to increase delay and decrease repeat rate by one-half 


04H to turn off keyboard repeat 


Returns: Nothing 


Notes: ™ Subfunctions OOH—04H are available on the PCjr but are not supported by the PC or 
PC/XT ROM BIOS. Subfunction 05H is available on PC/ATs with ROM BIOS’s dated 
11/15/85 and later, and on the PS/2. 


™ On the PC/AT and PS/2, the value in BH controls the amount of delay before the first 
repeat key is generated. The delay is always a multiple of 250 milliseconds: 
Value Delay (msec.) 


00H 250 
01H 500 
02H 750 
03H 1000 


™ Onthe PC/AT and PS/2, the value for the repeat rate in characters per second can be 
chosen from the following table: 


Value Repeat rate (characters per second) 
00H 30.0 
01H 26.7 
02H 24.0 
03H 21.8 
04H 20.0 
05H 18.5 
06H 17.1 
07H 16.0 
08H 15.0 


IBM ROM BIOS and Mouse Functions Reference 583 


Value Repeat rate (characters per second) 


OOH 13.3 
OAH 12.0 
OBH 10.9 
0CH 10.0 
ODH 9.2 
OEH 8.6 
OFH 8.0 
10H 75 
11H 6.7 
12H 6.0 
13H 5.5 
14H 5.0 
15H 4.6 
16H 4.3 
17H 4.0 
18H 3.7 
19H 3.3 
1AH 3.0 
1BH Z7 
1CH 2.5 
1DH 2.3 
1EH 2.1 
1FH 2.0 


Int 16H [PC] 
Function 04H 
Set keyclick 
Turns the keyboard click on or off. 
Call with: AH = 04H 
AL = subfunction 


OOH to turn off keyboard click 
01H to turn on keyboard click 


Returns: Nothing 


ae a ea eee 
Note: m This function is supported by the PCjr BIOS only. 
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Int 16H [AT] [PS/2] 
Function 05H 


Push character and scan code 


Places a character and scan code in the keyboard type-ahead buffer. 


Call with: AH = 05H 
CH = scan code 
CL = character 
Returns: If function successful 
Carry flag = clear 
AL = 0OH 


If function unsuccessful (type-ahead buffer is full) 
Carry flag = set 
AL = 01H 


Note: ™ This function can be used by keyboard enhancers and other utilities to interpolate 
keys into the data stream seen by application programs. 


Int 16H [AT] [PS/2] 
Function 10H (16) 


Read character from enhanced keyboard 


Reads a character and scan code from the keyboard type-ahead buffer. 


Call with: AH = 10H 
Returns: AH = keyboard scan code 
AL = ASCII character 
Note: ™ Use this function for the enhanced keyboard instead of Int 16H Function OOH. It 


allows applications to obtain the scan codes for the additional F11, F12, and cursor 
control keys. 
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Int 16H [AT] [PS/2] 
Function 11H (17) | 
Get enhanced keyboard status 


Determines whether a character is ready for input, returning a flag and also the character itself, if one 
is waiting. 


Call with: AH = 11H 


Returns: If key waiting to be input 


Zero flag =clear 
AH = keyboard scan code 
AL = character 
If no key waiting 
Zero flag =set 
Notes: = Use this function for the enhanced keyboard instead of Int 16H Function OOH. It 


allows applications to test for the additional F11, F12, and cursor control keys. 


m The character returned by this function when the zero flag is clear is not removed 
from the type-ahead buffer. The same character and scan code will be returned by 
the next call to Int 16H Function 10H. 


Int 16H [AT] [PS/2] 
Function 12H (18) 
Get enhanced keyboard flags 


Obtains the status of various enhanced keyboard special keys and keyboard driver states. 


Call with: AH = 12H 


Returns: AX = flags 

Significance (if set) 
right Shift key is down 
left Shift key is down 
either Ctrl key is down 
either Alt key is down 
Scroll Lock toggle is on 
Num Lock toggle is on 
Caps Lock toggle is on 
Insert toggle is on 

left Ctrl key is down 


Eb ede Are eee 
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Bit Significance (if set) 


9 left Alt key is down 

10 right Ctrl key is down 

11 right Alt key is down 

12 Scroll key is down 

13 Num Lock key is down 

14 Caps Lock key is down 

15 SysReq key is down 
Note: @ Use this function for the enhanced keyboard instead of Int 16H Function 02H. 
Int 17H [PC] [AT] [PS/2] 
Function 00H 
Write character to printer 


Sends a character to the specified parallel printer interface port and returns the current status of the port. 


Call with: AH = 00H 
AL = character 
DX = printer number (0 = LPT1, 1 = LPT2, 2 = LPT3) 
Returns: AH = status 
Bit Significance (if set) 
0 printer timed-out 
1 unused 
2 unused 
3 I/O error 
4 printer selected 
5 out of paper 
6 printer acknowledge 
7 printer not busy 
Int 17H [PC] [AT] [PS/2] 
Function 01H 
Initialize printer port 
Initializes the specified parallel printer interface port and returns its status. 
Call with: AH = 01H 
DX = printer number (0 = LPT1, 1 = LPT2, 2 = LPT3) 
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Returns: AH = status (see Int 17H Function 00H) 


Int 17H [PC] [AT] [PS/2] 
Function 02H 
Get printer status 


Returns the current status of the specified parallel printer interface port. 


Call with: AH = 02H 
DX = printer number (0 = LPT1, 1 = LPT2, 2 = LPT3) 
Returns: AH = status (see Int 17H Function 00H) 
Int 18H [PC] [AT] [PS/2] 
ROM BASIC 


Transfers control to ROM BASIC. 


Call with: Nothing 


Returns: Nothing 


Note: ® This function is invoked when the system is turned on or restarted if attempts to 
read a boot sector from the fixed disk or floppy disk drives are unsuccessful. 


Int 19H [PC] [AT] [PS/2] 


Reboots the operating system from the floppy disk or fixed disk drive. 


Call with: Nothing 


Returns: Nothing 


Notes: ® The bootstrap routine reads Sector 1, Track 0 into memory at location 0000:7CO0H 
and transfers control to the same address. If attempts to read a boot sector from the 
floppy disk or fixed disk are unsuccessful, control is transferred to ROM BASIC by 
execution of an Int 18H. 
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@ If location 0000:0472H does not contain the value 1234H, a memory test will be per- 
formed before reading the boot sector. 


Int 1AH [AT] [PS/2] 
Function 00H 


Get tick count 


Returns the contents of the clock tick counter. 


Call with: AH = 00H 
Returns: AL = rolled-over flag 


OOH if midnight not passed since last read 
<>00H if midnight was passed since last read 


CX:DX = tick count (high 16 bits in CX) 
Notes: ® This function is supported by the PC/XT and PCjr ROM BIOS, but is not present in 


the ROM BIOS for the original PC. 


The returned value is the cumulative number of clock ticks since midnight. There 


are 18.2 clock ticks per second. When the counter reaches 1,573,040, it is cleared to 
zero, and the rolled-over flag is set. 


The rolled-over flag is cleared by this function call, so the flag will only be returned 
nonzero once per day. 


Int 1AH Function 01H can be used to set the clock tick counter to an arbitrary 
32-bit value. 


Int 1AH [AT] [PS/2] 
Function 01H 


Set tick count 


Stores a 32-bit value in the clock tick counter. 


Call with: AH = 01H 
CX:DX = tick count (high 16 bits in CX) 


Returns: Nothing 
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Notes: m This function is supported by the PC/XT and PCjr ROM BIOS, but is not present in 
the ROM BIOS for the original PC. 
m Int 1AH Function 00H is used to read the value of the clock tick counter. 
w The rolled-over flag is cleared by this function call. 


Int 1AH [AT] [PS/2] 
Function 02H 
Get time 


Reads the current time from the CMOS time/date chip. 


Call with: AH = 02H 

Returns: CH = hours in binary coded decimal (BCD) 
CL = minutes in BCD 
DH = seconds in BCD 
DL = daylight-saving-time code 


OOH if standard time 
01H if daylight saving time 
and, if clock running 
Carry flag =clear 
or, if clock stopped 
Carry flag =set 


Int 1AH [AT] [PS/2] 
Function 03H 
Set time 


Sets the time in the CMOS time/date chip. 


Call with: AH = 03H 
CH = hours in binary coded decimal (BCD) 
CL = minutes in BCD 
DH = seconds in BCD 
DL = daylight-saving-time code 


OOH if standard time 
01H if daylight saving time 


Returns: Nothing 
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Int 1AH [AT] [PS/2] 


Reads the current date from the CMOS time/date chip. 


Call with: AH = 04H 

Returns: CH = century (19 or 20) in binary coded decimal (BCD) 
CL = year in BCD 
DH = month in BCD 
DL = day in BCD 


and, if clock running 
Carry flag =clear 
or, if clock stopped 
Carry flag =set 


Int 1AH [AT] [PS/2] 


Sets the date in the CMOS time/date chip. 


Callwith: AH = 05H 
CH = century (19 or 20) in binary coded decimal (BCD) 
CL = year in BCD 
DH = month in BCD 
DL = day in BCD 


Returns: Nothing 


Int 1AH [AT] [PS/2] 
Function 06H 
Set alarm 


Sets an alarm in the CMOS date/time chip. 
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Call with:. AH = 06H 


CH = hours in binary coded decimal (BCD) 
CL = minutes in BCD 
DH = seconds in BCD 

Returns: If function successful 


Carry flag = clear 
If function unsuccessful (alarm already set, or clock stopped) 
Carry flag =set 


Notes: = A side effect of this function is that the clock chip’s interrupt level (IRQ8) is enabled. 
@ Only one alarm may be active at any given time. The alarm occurs every 24 hours at 
the specified time until it is reset with Int 1AH Function 07H. 
= The program using this function must place the address of its interrupt handler for 
the alarm in the vector for Int 4AH. 


Int AH [AT] [PS/2] 
Function 07H 
Reset alarm 


Cancels any pending alarm request on the CMOS date/time chip. 


Returns: Nothing 


Note: ™ This function does not disable the clock chip’s interrupt level (IRQ8). 


Int 1AH [PS/2] 
Function 0AH (10) 
Get day count 


Returns the contents of the system’s day counter. 


Call with: AH = 0AH 
Returns: If function successful 
Carry flag =clear 
CX = count of days since January 1, 1980 


If function unsuccessful 
Carry flag = set 
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Int 1AH — [PS/2] 
Function OBH (11) 
Set day count 


Stores an arbitrary value in the system’s day counter. 


Call with: AH = 0BH 
CX = count of days since January 1, 1980 
Returns: If function successful 


Carry flag =clear 


If function unsuccessful 
Carry flag =set 


Int [AH [PC 
Function 80H (128) 
Set sound source 


hessond 


Sets up the source for tones that will appear on the PCjr’s “Audio Out” or RF modulator. 


Call with: AH = 80H 
AL = sound source 
OOH if 8253 programmable timer, channel 2 
01H if cassette input 


02H if “Audio In” line on I/O channel 
03H if sound generator chip 


Returns: Nothing 


Note: w This function is supported on the PCjr only. 


Int 33H 
Microsoft Mouse driver 


a SS SSS SSS SS SSS SSS 
The Microsoft Mouse driver makes its functions available to application programs via Int 33H. These 
functions have become a de facto standard for pointer device drivers of all varieties. Unlike the other 
function calls described in this section, the Microsoft Mouse driver is not part of the ROM BIOS but is 
loaded by a DEVICE= directive in the CONFIG.SYS file. All mouse-function information applies to the 
Microsoft Mouse driver version 6. Earlier versions of the driver may not support all of these functions. 
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Int 33H 
Function 00H 
Reset mouse and get status 


Initializes the mouse driver and returns the driver status. If the mouse pointer was previously visible, it is 
removed from the screen, and any previously installed user handlers for mouse events are disabled. 


Call with: Ax = 0000H 


Returns: If mouse support is available 
AX = FFFFH 
BX = number of mouse buttons 
If mouse support is not available 
AX = 0000H 


Ss 
Note: = After a call to this function, the mouse driver is initialized to the following state: 
— Mouse pointer at screen center (see Int 33H Functions 03H and 04H) 
— Display page for mouse pointer set to zero (see Int 33H Functions 1DH and 1EH) 
— Mouse pointer hidden (see Int 33H Functions 01H, 02H, and 10H) 
— Mouse pointer set to default arrow shape in graphics modes, or reverse block in 
text modes (see Int 33H Functions 09H and 0AH) 
— User mouse event handler disabled (see Int 33H Functions OCH and 14H) 
— Light pen emulation enabled (see Int 33H Functions 0DH and 0EH) 
~— Horizontal mickeys to pixels ratio at 8 to 8, vertical ratio at 16 to 8 (see Int 33H 
Function OFH) 
— Double speed threshold set to 64 mickeys/second (see Int 33H Function 19H) 
— Minimum and maximum horizontal and vertical pointer position limits set to in- 
clude the entire screen in the current display mode (see Int 33H Functions 07H 
and 08H) 


Int 33H 
Function 01H 
Show mouse pointer 


Displays the mouse pointer, and cancels any mouse pointer exclusion area previously defined with Int 
33H Function 10H. 


Call with: AX = 0001H 


Returns: Nothing 
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Note: = A counter is maintained which is decremented by calls to Int 33H Function 02H 
(Hide Mouse Pointer) and incremented (if nonzero) by this function. When the 
counter is zero or becomes zero, the mouse pointer is displayed. When the mouse 
driver is reset with Int 33H Function 00H, the counter is forced to —1. 


Int 33H 
Function 02H 
Hide mouse pointer 


Removes the mouse pointer from the display. The driver continues to track the mouse position. 


Call with: AX = 0002H 


Returns: Nothing 


Note: = Acounter is maintained which is decremented by calls to this function and incre- 
mented Cif nonzero) by Int 33H Function 01H (Show Mouse Pointer). When the 
counter is zero, the mouse pointer is displayed. When the mouse driver is reset with 
Int 33H Function 00H, the counter is forced to —1. 


Int 33H 
Function 03H 
Get mouse position and button status 


Returns the current mouse button status and pointer position. 


Call with: AX = 0003H 
Returns: Bx = mouse button status 
Bit(s) Significance (if set) 
0 left button is down 
1 right button is down 
2 center button is down 
3-15 reserved (0) 
CX = horizontal CX) coordinate 
DX = vertical (Y) coordinate 
Note: = Coordinates are returned in pixels regardless of the current display mode. Position 


(x,y) = (0,0) is the upper left corner of the screen. 
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Int 33H 
Function 04H 
Set mouse pointer position 


Sets the position of the mouse pointer. The pointer is displayed at.the new position unless it has been 
hidden with Int 33H Function 02H, or the new position lies within an exclusion area defined with Int 33H 
Function 10H. 


Call with: Ax = 0004H 
CX = horizontal CX) coordinate 
DX = vertical (Y) coordinate 


Returns: Nothing 


Notes: = Coordinates are specified in pixels regardless of the current display mode. Position 
(x,y) = (0,0) is the upper left corner of the screen. 
m The position is adjusted if necessary to lie within the horizontal and vertical limits 
specified with a previous call to Int 33H Functions 07H and 08H. 


Int 33H 
Function 05H 
Get button press information 


Returns the current status of all mouse buttons, and the number of presses and position of the last press 
for a specified mouse button since the last call to this function for that button. The press counter for the 
button is reset to zero. 


Call with: Ax = 0005H 
BX = button identifier 
O = left button 
1 = right button 
2 = center button 
Returns: AX = button status 
Bit(s) Significance (if set) 
0 left button is down 
1 right button is down 
2 center button is down 
3-15 reserved (0) 
BX = button press counter 
CX = horizontal CX) coordinate of last button press 
DX = vertical CY) coordinate of last button press 
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Int 33H 
Function 06H 
Get button release information 


Returns the current status of all mouse buttons, and the number of releases and position of the last release 


for a specified mouse button since the last call to this function for that button. The release counter for the 
button is reset to zero. 


Call with: AX = 0006H 
BX = button identifier 
O = left bution 
1 = right button 
2 = center button 
Returns: AX = button status 
Bit(s) Significance (if set) 
0 left button is down 
1 right button is down 
2 center button is down 
3-15 reserved (0) 
BX = button release counter 
CX = horizontal CX) coordinate of last button release 
DX = vertical (Y) coordinate of last button release 


Int 33H 
Function 07H 
Set horizontal limits for pointer 


Limits the mouse pointer display area by assigning minimum and maximum horizontal CX) coordinates 
for the mouse pointer. 


Call with: Ax = 0007H 
CX = minimum horizontal CX) coordinate 
DX = maximum horizontal CX) coordinate 


Returns: Nothing 


Notes: ws Ifthe minimum value is greater than the maximum value, the two values are 
swapped. 


m= The mouse pointer will be moved if necessary so that it lies within the specified 
horizontal coordinates. 
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= See also Int 33H Function 10H, which defines an exclusion area for the mouse 
pointer. 


Int 33H 
Function 08H 
Set vertical limits for pointer 


Limits the mouse pointer display area by assigning minimum and maximum vertical (Y) coordinates for 
the mouse pointer. 


Call with: AX = 0008H 
CX = minimum vertical CY) coordinate 
DX = maximum vertical CY) coordinate 


Returns: Nothing 


Notes: = If the minimum value is greater than the maximum value, the two values are 
swapped. 
= The mouse pointer will be moved if necessary so that it lies within the specified 
vertical coordinates. 
= See also Int 33H Function 10H, which defines an exclusion area for the mouse 
pointer. 


Int 33H 
Function 09H 
Set graphics pointer shape 


Defines the shape, color, and hot spot of the mouse pointer in graphics modes. 


Callwith: Ax = 0009H 
BX = hot spot offset from left 
CX = hot spot offset from top 
ES:DX = segment:offset of pointer image buffer 


Returns: Nothing 


Notes: = The pointer image buffer is 64 bytes long. The first 32 bytes contain a bit mask 
which is ANDed with the screen image, and the second 32 bytes contain a bit mask 
which is XORed with the screen image. 

= The hot spot is relative to the upper left corner of the pointer image, and each pixel 
offset must be in the range —16 through 16. In display modes 4 and 5, the horizontal 
offset must be an even number. 
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Int 33H 
Function 0AH (10) 
Set text pointer type 


Defines the shape and attributes of the mouse pointer in text modes. 


Call with: AX = 000AH 
BX = pointer type 
O = software cursor 
1 = hardware cursor 
Cx = AND mask value Cif BX = 0) or 
starting line for cursor (if BX = 1) 
DX = XOR mask value (if BX = 0) or 


ending line for cursor (if BX = 1) 


Returns: Nothing 


Notes: = If the software text cursor is selected (BX = 0), the masks in CX and DX are mapped 
as follows: 
Bit(s) Significance 
0-7 character code 
8-10 foreground color 
11 intensity 
12-14 background color 
15 blink 


For example, the following values would yield a software mouse cursor that inverts 
the foreground and background colors: 


AX = 000AH 
BX = 0000H 
CX = 77FFH 
DX = 7700H 


m= When the hardware text cursor is selected (BX = 1), the values in CX and DX are the 
starting and ending scan lines for the blinking cursor generated by the video adapter. 
The maximum scan line which may be used depends on the type of adapter and the 


current display mode. 
Int 33H 
Function OBH (11) 


Read mouse motion counters 


Returns the net mouse displacement since the last call to this function. The returned value is in mickeys; 
a positive number indicates travel to the right or downwards, a negative number indicates travel to the left 
or upwards. One mickey represents approximately '/200 of an inch of mouse movement. 
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Call with: Ax = 000BH 


Returns: CX = horizontal (X) mickey count 
DX = vertical CY) mickey count 


Se 
Int 33H 


Function 0CH (12) 


Set user-defined mouse event handler 
a 


Sets the address and event mask for an application program’s mouse event handler. The handler is called 
by the mouse driver whenever the specified mouse events occur. 


Call with: Ax = 000CH 
CX = event mask 
Bit(s) Significance (if set) 
mouse movement 
left button pressed 
left button released 
right button pressed 
right button released 
center button pressed 
center button released 
7-15 reserved (0) 
ES:DX = segment:offset of handler 


ON MN BR ON - © 


Returns: Nothing 


Notes: m The user-defined event handler is entered from the mouse driver by a far call with 
registers set up as follows: 
AX mouse event flags (see event mask) 
BX button state 
Bit(s) Significance (if set) 
0 left button is down 
1 right button is down 
2 center button is down 
3-15 reserved (0) 
CX horizontal CX) pointer coordinate 
DX vertical CY) pointer coordinate 
SI last raw vertical mickey count 
DI last raw horizontal mickey count 
DS mouse driver data segment 


= If an event does not generate a call to the user-defined handler because its bit is not 
set in the event mask, it is still reported in the event flags during calls to the handler 
for events which are enabled. 
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® Calls to the handler are disabled with Int 33H Function 00H or by calling this func- 
tion with an event mask of zero. 


® See also Int 33H Functions 14H and 18H. 


Int 33H 
Function 0DH (13) 
Turn on light pen emulation 


Enables light pen emulation by the mouse driver for IBM BASIC. A “pen down” condition is created by 
pressing the left and right mouse buttons simultaneously. 


Call with: AX = 000DH 


Returns: Nothing 


Int 33H 
Function 0EH (14) 
Turn off light pen emulation 


Disables light pen emulation by the mouse driver for IBM BASIC. 


Call with: AX = 000EH 


Returns: Nothing 


Function OFH (15) 
Set mickeys to pixels ratio 


Sets the number of mickeys per 8 pixels for horizontal and vertical mouse motion. One mickey represents 
approximately 1/200 of an inch of mouse travel. 


Call with: AX = 000OFH 
CX = horizontal mickeys (1-32,767, default = 8) 
DX = vertical mickeys (1-32,767, default = 16) 


Returns: Nothing 
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Int 33H 
Function 10H (16) 
Set mouse pointer exclusion area 


Defines an exclusion area for the mouse pointer. When the mouse pointer lies within the specified area, it 
is not displayed. 


Callwith: Ax = 0010H 
CX = upper left X coordinate 
DX = upper left Y coordinate 
SI = lower right X coordinate 
DI = lower right Y coordinate 


Returns: Nothing 


Note: = The exclusion area is replaced by another call to this function or cancelled by Int 
33H Functions 00H or 01H. 


Int 33H 
Function 13H (19) 
Set double speed threshold 


Sets the threshold speed for doubling pointer motion on the screen. The default threshold speed is 64 
mickeys/second. 


Call with: Ax = 0013H 
DX = threshold speed in mickeys/second 


Returns: Nothing 


Note: = Doubling of pointer motion can be effectively disabled by setting the threshold to a 
very large value (such as 10,000). 


602 _ Section III 


Int 33H 
Function 14H (20) 
Swap user-defined mouse event handlers 


Sets the address and event mask for an application program’s mouse event handler and returns the ad- 
dress and event mask for the previous handler. The newly installed handler is called by the mouse driver 
whenever the specified mouse events occur. 


Call with: Ax = 0014H 
CX = event mask 
Bit(s) Significance (if set) 


0 mouse movement 
1 left button pressed 
2 left button released 
3 right button pressed 
4 right button released 
5 center button pressed 
6 center button released 
7-15 reserved (0) 
ES:DX = segment:offset of event handler 
8 nn ee ee 
Returns: CX = previous event mask 
ES:DX = segment:offset of previous handler 
Notes: ™ The Notes for Int 33H Function OCH describe the information passed to the user- 


defined event handler. See also Int 33H Function 18H. 


™ Calls to the event handler are disabled with Int 33H Function 00H or by setting an 
event mask of zero. 


Int 33H 
Function 15H (21) 
Get mouse save state buffer size 


Gets the size of the buffer required to store the current state of the mouse driver. 


Call with: AX = 0015H 
Returns: BX = buffer size (bytes) 
Note: ® See also Int 33H Functions 16H and 17H. 
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———— 
Int 33H 


Function 16H (22) 


Save mouse driver state 
SS Sse SS sss 


Saves the mouse driver state in a user buffer. The minimum size for the buffer must be determined by a 
previous call to Int 33H Function 15H. 


Call with: Ax = 0016H 


ES:DX = segment:offset of buffer 


a ne 


Returns: Nothing 


Note: ™ Call this function before executing a child program with Int 21H Function 4BH 
(EXEC), in case the child also uses the mouse. After the EXEC call, restore the pre- 
vious mouse driver state with Int 33H Function 17H. 


———— 
Int 33H 


Function 17H (23) 


Restore mouse driver state 
ee 


Restores the mouse driver state from a user buffer. 


Call with: Ax = 0017H 
ES:DX = segment:offset of buffer 


eee 
Returns: Nothing 


Note: ™ The mouse driver state must have been previously saved into the same buffer with 
Int 33H Function 16H. The format of the data in the buffer is undocumented and 
subject to change. 


ST UEEaREEEEE 
Int 33H 


Function 18H (24) 


Set alternate mouse event handler 
ee ee 


Sets the address and event mask for a an application program mouse event handler. As many as three 
handlers with distinct event masks can be registered with this function. When an event occurs that 
matches one of the masks, the corresponding handler is called by the mouse driver. 
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Call with: AX = 0018H 


CX = event mask 
Bit(s) Significance (if set) 
0 mouse movement 
1 left button pressed 
2 left button released 
3 right button pressed 
4 right button released 
5 Shift key pressed during button press or release 
6 Ctrl key pressed during button press or release 
7 Alt key pressed during button press or release 
8-15 reserved (0) 
ES:DX = segment:offset of handler 
a a Se 
Returns: If function successful 
AX = 0018H 
If function unsuccessful 
AX = FFFFH 
Sh i a 8 SS 
Notes: ® When this function is called, at least one of the bits 5, 6, and 7 must be set in 
register CX. 


® The user-defined event handler is entered from the mouse driver by a far call with 
registers set up as follows: 


AX mouse event flags (see event mask) 
BX button state 
Bit(s) Significance (if set) 
0 left button is down 
1 right button is down 
2 center button is down 
3-15 reserved (0) 
CX horizontal CX) pointer coordinate 
DX vertical (Y) pointer coordinate 
SI last raw vertical mickey count 
DI last raw horizontal mickey count 
DS mouse driver data segment 


® if an event does not generate a call to the user-defined handler because its bit is not 
set in the event mask, it can still be reported in the event flags during calls to the 
handler for events that are enabled. 


™ Calls to the handler are disabled with Int 33H Function 00H. 
® See also Int 33H Functions OCH and 14H. 
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————— 
Int 33H 


Function 19H (25) 
Get address of alternate mouse event handler 


Returns the address for the mouse event handler matching the specified event mask. 


Call with: Ax = 0019H 
CX = event mask (see Int 33H Function 18H) 


Returns: If function successful 
CX = event mask 
ES:DX = segment:offset of alternate event handler 


If function unsuccessful (no handler installed or event mask does not match any 
installed handler) 
CX = 0000H 


Note: @ Int 33H Function 18H allows as many as three event handlers with distinct event 
masks to be installed. This function can be called to search for a handler that 
matches a specific event, so that it can be replaced or disabled. 


—— 
Int 33H 


Function 1AH (26) 


Set mouse sensitivity 
SaaS SSS 


Sets the number of mickeys per 8 pixels for horizontal and vertical mouse motion and the threshold speed 
for doubling pointer motion on the screen. One mickey represents approximately 1/200 of an inch of 
mouse travel. 


Call with: Ax = 001AH 
BX = horizontal mickeys (1—32,767, default = 8) 
CX = vertical mickeys (1-32,767, default = 16) 
DX = double speed threshold in mickeys/second (default = 64) 


i 
Returns: Nothing 


———,—.evwoa eee 


Note: = See also Int 33H Functions OFH and 13H, which allow the mickeys to pixels ratio 
and threshold speed to be set separately, and Int 33H Function 1BH, which returns 
the current sensitivity values. 
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Int 33H 
Function 1BH (27) 
Get mouse sensitivity 


Returns the current mickeys to pixels ratios for vertical and horizontal screen movement and the 
threshold speed for doubling of pointer motion. | 


Call with: AX = 001BH 
Returns: BX = horizontal mickeys (1-32,767, default = 8) 
CX = vertical mickeys (1-32,767, default = 16) 
DX = double speed threshold in mickeys/second (default = 64) 
Note: = See also Int 33H Functions OFH, 13H, and 1AH. 
a eS 
Int 33H 


Function 1CH (28) 
Set mouse interrupt rate 


A 


Sets the rate at which the mouse driver polls the status of the mouse. Faster rates provide better resolu- 
tion in graphics mode but may degrade the performance of application programs. 


Call with: AX = 001CH 
BX = interrupt rate flags 
Bit(s) Significance 
no interrupts allowed 
30 interrupts/second 
50 interrupts/second 
100 interrupts/second 
200 interrupts/second 
—15 reserved (0) 


Wo Ob N © 


Returns: Nothing 


nn eddy 


Notes: ™ This function is applicable for the InPort Mouse only. 
= If more than one bit is set in register BX, the lowest order bit prevails. 
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ee 
Int 33H 


Function 1DH (29) 
Select pointer page 


Selects the display page for the mouse pointer. 


Call with: Ax = 001DH 
BX = page 


Returns: Nothing 


Note: = The valid page numbers depend on the current display mode. See Int 10H 
Function 05H. 


Int 33H 
Function 1EH (30) 
Get pointer page 


Returns the current display page for the mouse pointer. 


Call with: Ax = 001EH 
Returns: BX = page 


Int 33H 
Function 1FH (31) 
Disable mouse driver 


Disables the mouse driver and returns the address of the previous Int 33H handler. 


Call with: Ax = 001FH 


Returns: If function successful 
AX = 001FH 
ES:BX = segment:offset of previous Int 33H handler 


If function unsuccessful 
AX = FFFFH 
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Notes: ™ When this function is called, the mouse driver releases any interrupt vectors it has 
captured other than Int 33H (which may include Int 10H, Int 71H, and/or Int 74H). 
The application program can complete the process of logically removing the mouse 
driver by restoring the original contents of the Int 33H vector with Int 21H Function 
25H, using the address returned by this function in ES:BX. 


# See also Int 33H Function 20H. 


Int 33H 
Function 20H (32) 
Enable mouse driver 


Enables the mouse driver and the servicing of mouse interrupts. 


Call with: AX = 0020H 


Returns: Nothing 


Note: ® See also Int 33H Function 1FH. 


Int 33H 
Function 21H (33) 
Reset mouse driver 


Resets the mouse driver and returns driver status. If the mouse pointer was previously visible, it is 
removed from the screen, and any previously installed user handlers for mouse events are disabled. 


Call with: Ax = 0021H 
Returns: If mouse support is available 
AX = FFFFH 
BX = number of mouse buttons 
If mouse support is not available 
AX = 0021H 
Note: ™ This function differs from Int 33H Function OOH in that there is no initialization of 


the mouse hardware. 
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Int 33H 
Function 22H (34) 
Set language for mouse driver messages 


Selects the language that will be used by the mouse driver for prompts and error messages. 


Call with: AX = 0022H 
BX = language number 

O = English 

1 = French 

2 = Dutch 

3 = German 

4 = Swedish 

5 = Finnish 

6 = Spanish 

vi = Portuguese 

8 = Italian 
Returns: Nothing 
Note: ™ This function is only available in international versions of the Microsoft Mouse 


driver. 


Int 33H 
Function 23H (35) 
Get language number 


Returns the number of the language that is used by the mouse driver for prompts and error messages. 


Call with: Ax = 0023H 

Returns: BX = language number (see Int 33H Function 22H) 

Note: ™ This function is only available in international versions of the Microsoft Mouse 
driver. 
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Int 33H 
Function 24H (36) 
Get mouse information 


Returns the mouse driver version number, mouse type, and:the IRQ number of the interrupt used by the 
mouse adapter. 


Call with: AX = 0024H 
Returns: BH = major version number (6 for version 6.10, etc.) 
BL = minor version number (OAH for version 6.10, etc.) 
CH = mouse type 
1 = bus mouse 
2 = serial mouse 
3 = InPort mouse 
4 = PS/2 mouse 
5 = HP mouse 
CL = IRQ number 
O = PS/2 


2,3,4,5,0r7 =IRQnumber 
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ECTION IV 


t 


Lotus/intel/ 
Microsoft EMS 


Functions 


~~ Reference > 


Notes to the Reader 


The Lotus/Intel/Microsoft Expanded Memory Specification (EMS) defines 
a hardware/software subsystem, compatible with 80x86-based microcom- 
puters running MS-DOS, that allows applications to access as much as 32 
MB of bank-switched random-access memory. The software component, 
called the Expanded Memory Manager (EMM), is installed during system 
initialization by a DEVICE= directive in the CONFIG.SYS file in the root 
directory on the boot disk. 


After ensuring that the EMM is present (see Chapter 11), an application 
program communicates directly with the EMM using software interrupt 
67H. A particular EMM function is selected by the value in register AH and 
a success or error status is returned in register AH (error codes are listed 
on pages 207-209). Other parameters and results are passed or returned 
in registers or buffers. | 


An icon in each function heading indicates the EMS version in which that 
function was first supported. You can assume that the function is available 
in all subsequent EMS versions unless explicitly noted otherwise. 


Version icons used in the synopsis, parameters, results, or Notes section 
refer to specific minor or major EMS versions, unless they include a + sign 
to indicate a version and all subsequent versions. 


The material in this section has been verified against the Expanded 
Memory Specification version 4.0, dated October 1987, Intel part number 
300275-005. This document can be obtained from Intel Corporation, 5200 
N.E. Elam Young Parkway, Hillsboro, OR 97124. 


Summary of EMM Functions 
Function Subfunction Description 
40H (64) Get Status 
41H (65) Get Page Frame Address 
42H (66) Get Number of Pages 
43H (67) Allocate Handle and Pages 
44H (68) Map Expanded Memory Page 
45H (69) Release Handle and Expanded Memory 
46H (70) Get Version 
47H (71) Save Page Map 
48H (72) Restore Page Map 
49H (73) Reserved 
4AH (74) Reserved 
4BH (75) Get Handle Count 
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(continued) 


Section IV 


Summary of EMM Functions continued 


Function Subfunction Description 

4CH (76) Get Handle Pages 

4DH (77) Get Pages for All Handles 

4EH (78) 00H Save Page Map 

4EH (78) 01H Restore Page Map 

4FH (78) 02H Save and Restore Page Map 

4EH (78) 03H Get Size of Page Map Information 

4FH (79) 00H Save Partial Page Map 

4FH (79) 01H Restore Partial Page Map 

4FH (79) 02H Get Size of Partial Page Map Information 

50H (80) 00H Map Multiple Pages by Number 

50H (80) 01H Map Multiple Pages by Address 

51H (81) Reallocate Pages for Handle 

52H (82) 00H Get Handle Attribute 

52H (82) 01H Set Handle Attribute 

52H (82) 02H Get Attribute Capability 

53H (83) 00H Get Handle Name 

53H (83) 01H Set Handle Name 

54H (84) OOH Get All Handle Names 

54H (84) 01H Search for Handle Name 

54H (84) 02H Get Total Handles 

55H (85) 00H Map Pages by Number and Jump 

55H (85) 01H Map Pages by Address and Jump 

56H (86) 00H Map Pages by Number and Call 

56H (86) 01H Map Pages by Address and Call 

56H (86) 02H Get Space for Map Page and Call 

57H (87) 00H Move Memory Region 

57H (87) 01H Exchange Memory Regions 

58H (88) 00H Get Addresses of Mappable Pages 

58H (88) 01H Get Number of Mappable Pages 

59H (89) 00H Get Hardware Configuration 

59H (89) 01H Get Number of Raw Pages 

5AH (90) 00H Allocate Handle and Standard Pages 

5AH (90) 01H Allocate Handle and Raw Pages 

5BH (91) 00H Get Alternate Map Registers 

5BH (91) 01H Set Alternate Map Registers 

5BH (91) 02H Get Size of Alternate Map Register Save Area 

5BH (91) 03H Allocate Alternate Map Register Set 

5BH (91) 04H Deallocate Alternate Map Register Set 

5BH (91) 05H Allocate DMA Register Set 

5BH (91) 06H Enable DMA on Alternate Map Register Set 

5BH (91) 07H Disable DMA on Alternate Map Register Set 

5BH (91) 08H Deallocate DMA Register Set 

5CH (92) Prepare Expanded Memory Manager for 
Warm Boot 

5DH (93) 00H Enable EMM Operating-System Functions 

5DH (93) 01H Disable EMM Operating-System Functions 

5DH (93) 02H Release Access Key 
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Int 67H [EMS 3.0] 
Function 40H (64) 
Get status 


Returns a status code indicating whether the expanded memory software and hardware are present and 
functional. 


Call with: AH = 40H 


Returns: If function successful 
AH = 00H 
If function unsuccessful 
AH = error code 


Note: = This call should be used only after an application has established that the Expanded 
Memory Manager is in fact present, using one of the techniques described in 
_ Chapter 11. 


Int 67H [EMS 3.0] 
Function 41H (65) 
Get page frame address 


Returns the segment address of the page frame used by the Expanded Memory Manager. 


Call with: AH = 41H 
Returns: If function successful 
AH = 00H 
BX = segment base of page frame 
If function unsuccessful 
AH = error code 
Notes: = The page frame is divided into four 16 KB pages, which are used to map logical ex- 


panded memory pages into the physical memory space of the CPU. 


The application need not have already acquired an EMM handle to use this function. 


= [EMS 4.0] Mapping of expanded memory pages is not necessarily limited to the 64 
KB page frame. See also Int 67H Function 58H Subfunction 00H. 


616 Section IV 


Int 67H [EMS 3.0] 
Function 42H (66) 
Get number of pages 


Obtains the total number of logical expanded memory pages present in the system and the number of 
pages that are not already allocated. 


Call with: AH = 42H 


Returns: If function successful 


AH = 00H 
BX = unallocated pages 
DX = total pages 
If function unsuccessful 
AH = error code 
Notes: w The application need not have already acquired an EMM handle to use this function. 


m [EMS 4.0] See also Int 67H Function 59H Subfunction 01H. 


Int 67H | [EMS 3.0] 
Function 43H (67) 
Allocate handle and pages 


Obtains an EMM handle and allocates logical pages of expanded memory to be controlled by that handle. 


Call with: AH = 43H 

BX = number of pages to allocate (must be nonzero) 
Returns: If function successful 

AH = 00H 

DX = EMM handle 

If function unsuccessful 

AH = error code 
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Notes: ™ This is the equivalent of a file open function for the expanded memory manager. 
The handle that is returned is analogous to a file handle and owns a certain number 
of expanded memory pages. The handle must be used with every subsequent re- 
quest to map memory and must be released by a close operation before the 
application terminates. 


= This function may fail because there are no handles left to allocate or because there 
is an insufficient number of expanded memory pages to satisfy the request. In the 
latter case, Int 67H Function 42H can be used to determine the actual number of 
pages available. 


= [EMS 4.0] Int 67H Function 51H can be called to change the number of pages allo- 
cated to an EMM handle. 


= [EMS 4.0] The pages allocated by this function are always 16 KB for compatibility 
with earlier versions of EMS. See also Int 67H Function 5AH Subfunctions 00H and 
01H. 


m [EMS 4.0] Handle 0000H is always available for use by the operating system, and a 


prior call to this function is not required. The operating system must call Int 67H 
Function 51H to assign the desired number of pages to its reserved handle. 


Int 67H [EMS 3.0] 
Function 44H (68) 
Map expanded memory page 


Maps one of the logical pages of expanded memory assigned to a handle onto a physical memory page 
that can be accessed by the CPU. 


Call with: AH = 44H 
AL = physical page 
BX = logical page 
DX = EMM handle 
Returns: If function successful 
AH = 00H 
If function unsuccessful 
AH = error code 
Notes: = The logical page number is in the range {0...—1}, where m is the number of pages 


allocated or reallocated to the handle by a previous call to Int 67H Function 43H, 
51H, or 5AH. Logical pages allocated by Int 67H Function 43H or Function 5AH Sub- 
function OOH are always 16 KB long; logical pages allocated by Int 67H Function 
5AH Subfunction 01H are referred to as raw pages and are not necessarily 16 KB. 

= [EMS 3] The physical page is in the range 0-3 and lies within the EMM page frame, 
whose base address is obtained from Int 67H Function 41H. 
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m [EMS 4.0] A list of the available physical pages and their addresses may be obtained 
from Int 67H Function 58H Subfunction OOH. 

mw [EMS 4.0] If this function is called with BX = —1, the specified physical page is un- 
mapped (made inaccessible for reading or writing). 


Int 67H [EMS 3.0] 
Function 45H (69) 
Release handle and expanded memory 


Deallocates the expanded memory pages assigned to a handle and then releases the handle. 


Call with: AH = 45H 
DX = EMM handle 
Returns: If function successful 
AH = 00H 
If function unsuccessful 
AH = error code 
Notes: m If this function is not called before a program terminates, the EMS pages it owned 


remain unavailable until the system is restarted. Programs that use EMS should in- 
stall their own Ctrl-C handlers and critical-error handlers (ints 23H and 24H) so that 
they cannot be terminated unexpectedly. 


m [EMS 4.0] When a handle is released, its name is set to all ASCII nulls. 


Int 67H [EMS 3.0] 
Function 46H (70) 
Get version 


Returns the EMS version supported by the expanded memory manager. 


Call with: AH = 46H 
Returns: If function successful 

AH = 00H 

AL = version number 


If function unsuccessful 
AH = error code 
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Notes: m The version number is returned in binary code decimal (BCD) format, with the in- 
teger portion in the upper 4 bits of AL and the fractional portion in the lower 4 bits. 
For example, under an EMM that supports EMS version 3.2, AL is returned as the 
value 32H. | 


m Applications should always check the EMM version number to ensure that all of the 
EMM functions they require are available. 


Int 67H [EMS 3.0] 
Function 47H (71) 
Save page map 


Saves the contents of the page-mapping registers on the expanded memory hardware, associating those 
contents with a particular EMM handle. 


Call with: AH = 47H 
DX = EMM handle 


Returns: If function successful 
AH = 00H 
If function unsuccessful 
AH = error code 


Notes: m This function is used by interrupt handlers or device drivers that must access ex- 
panded memory. The EMM handle supplied to this function is the handle that was 
assigned to the handler or driver during its own initialization sequence, not to the 
program that was interrupted. 


m= The mapping context is restored by a subsequent call to Int 67H Function 48H. 
= [EMS 4.0] This function saves only the mapping state for the 64 KB page frame 
defined in EMS 3. Programs that are written to take advantage of the additional 


capabilities of EMS 4.0 should use Int 67H Function 4EH or 4FH in preference to 
this function. 


Int 67H [EMS 3.0] 
Function 48H (72) 
Restore page map 


Restores the contents of the page-mapping registers on the expanded memory hardware to the values 
associated with the specified handle by a previous call to Int 67H Function 47H. 
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Call with: AH = 48H 
Dx = EMM handle 


Returns: If function successful 
AH = 00H 
If function unsuccessful 
AH = error code 


Notes: a This function is used by interrupt handlers or device drivers that must access ex- 
panded memory. The EMM handle supplied to this function is the handle that was 
assigned to the handler or driver during its own initialization sequence, not to the 
program that was interrupted. 


m [EMS 4.0] This function restores only the mapping state for the 64 KB page frame 
defined in EMS 3. Programs that are written to take advantage of the additional 
capabilities of EMS 4.0 should use Int 67H Function 4EH or 4FH in preference to 
this function. 


Int 67H [EMS 3.0] 
Function 49H (73) 
Reserved 


This function was defined in EMS version 3.0 but is not documented for later EMS versions, so it should be 
avoided in application programs. 


Int 67H [EMS 3.0] 
Function 4AH (74) 
Reserved 


This function was defined in EMS version 3.0 but is not documented for later EMS versions, so it should be 
avoided in application programs. 


Int 67H [EMS 3.0] 
Function 4BH (75) 
Get handle count 


Returns the number of active expanded memory handles. 
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Call with: AH = 4BH 


Returns: If function successful 
AH = 00H 
BX = number of active EMM handles 
If function unsuccessful 
AH = error code 


Notes: = Ifthe returned number of EMM handles is zero, the expanded memory manager is 
idle, and none of the expanded memory is in use. 
@ The value returned by this function is not necessarily the same as the number of 
programs using expanded memory because one program may own multiple EMM 
handles. 


= The number of active EMM handles never exceeds 255. 


Int 67H [EMS 3.0] 
Function 4CH (76) 
Get handle pages 


Returns the number of expanded memory pages allocated to a specific EMM handle. 


Call with: AH = 4CH 
DX = EMM handle 
Returns: If function successful 
AH = 00H 
BX = number of EMM pages 
If function unsuccessful 
AH = error code 
Notes: = [EMS 3] The total number of pages allocated to a handle never exceeds 512. A handle 


never has zero pages allocated to it. 


m [EMS 4.0] The total number of pages allocated to a handle never exceeds 2048. A 
handle may have zero pages of expanded memory. 
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Int 67H [EMS 3.0] 
Function 4DH (77) 
Get pages for all handles 


Returns an array that contains all the active handles and the number of expanded memory pages associ- 
ated with each handle. 


Call with: AH = 4DH 
ES:DI = segment:offset of buffer (see Notes) 


Returns: If function successful 
AH = 00H 
BX = number of active EMM handles 
and buffer filled in as described in Notes 
If function unsuccessful 


AH = error code 
. Notes: = The buffer is filled in with a series of DWORD (32-bit) entries, one per active EMM 


handle. The first word of an entry contains the handle, and the second word contains 
the number of pages allocated to that handle. 

= The maximum number of active handles is 256 (including the operating system 
handle 0), so a buffer size of 1024 bytes is adequate in all cases. 


Int 67H [EMS 3.2] 
Function 4EH (78) Subfunction 00H 
Save page map 


Saves the current page-mapping state of the expanded memory hardware in the specified buffer. 


Call with: AH = 4EH 
AL = 00H 
ES:DI = segment:offset of buffer (see Notes) 


Returns: If function successful 
AH = 00H 


and buffer filled in with mapping information (see Notes) 


If function unsuccessful 
AH = error code 
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Notes: w The buffer receives the information necessary to restore the state of the mapping 
registers using Int 67H Function 4EH Subfunction 01H. The format of the informa- 
tion may vary. 

m The size of the buffer required by this function can be determined with Int 67H 
Function 4EH Subfunction 03H. 


sw Unlike Int 67H Function 47H, this function does not require a handle. 


Int 67H [EMS 3.2] 
Function 4EH (78) Subfunction 01H 
Restore page map 


Restores the page-mapping state of the expanded memory hardware using the information in the speci- 
fied buffer. 


Call with: AH = 4EH 
AL = 01H 
DS:SI = segment:offset of buffer (see Notes) 
Returns: If function successful 
AH = 00H 
If function unsuccessful 
AH = error code 
Notes: w The buffer contains information necessary to restore the state of the mapping regis- 


ters from a previous call to Int 67H Function 4EH Subfunction 00H or 02H. The 
format of the information may vary. 


w Unlike Int 67H Function 48H, this function does not require a handle. 


Int 67H | [EMS 3.2] 
Function 4EH (78) Subfunction 02H 
Save and restore page map 


Saves the current page-mapping state of the expanded memory hardware in a buffer and then sets the 
mapping state using the information in another buffer. 


Call with: AH = 4EH 
AL = 02H 
DS:SI = segment:offset of buffer containing mapping information (see Notes) 
ES:DI = segment:offset of buffer to receive mapping information (see Notes) 


624 ~—=s Section IV 


Returns: If function successful 
AH = 00H 
and buffer pointed to by ES:DI filled in with mapping information (see Notes) 
If function unsuccessful 


AH = error code 
Notes: ® The buffer addressed by DS:SI contains information necessary to restore the state of 


the mapping registers from a previous call to Int 67H Function 4EH Subfunction 00H 
or 02H. The format of the information may vary. 


@ The sizes of the buffers required by this function can be determined with Int 67H 
Function 4EH Subfunction 03H. 


® Unlike Int 67H Functions 47H and 48H, this function does not require a handle. 


Int 67H [EMS 3.2] 
Function 4EH (78) Subfunction 03H 
Get size i page mp snasiaisammecenias 


Returns the size of i buffer shat is pean to receive page-mapping fafeamaione using Int 67H E Func- 
tion 4EH Subfunctions 00H and 02H. 


Call with: AH = 4EH 
AL = 03H 
Returns: If function successful 
AH = 00H 
AL = size of buffer (bytes) 
If function unsuccessful 
AH = error code 


Int 67H [EMS 4, 0] 
Function 4FH (79) Subfunction 00H 
Save pare page map 


Saves the state of a subset of the sxetntied memory page-mapping registers in fe es asecined buffer. 


Call with: AH = 4FH 
AL = 00H 
DS:SI = segment:offset of map list (see Notes) 
ES:DI = segment:offset of buffer to receive mapping state (see Notes) 
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Returns: If function successful 
AH. = 0OH 


and buffer filled in with mapping information (see Notes) 


If function unsuccessful 
AH = error code 


Notes: = The map list contains the number of mappable segments in the first word, followed 
by the segment addresses of the mappable memory regions (one segment per word). 
" To determine the size of the buffer required for the mapping state, use Int 67H Func- 
tion 4FH Subfunction 02H. 


Int [EMS 4.0] 
Function 4FH (79) Subfunction 01H 


Restore partial page map 


Restores the state of a subset of the expanded memory page-mapping registers. 


Call with: AH = 4FH 
AL = 01H 
DS:SI = segment:offset of buffer (see Note) 
Returns: If function successful 
AH = 00H 
If function unsuccessful 
AH = error code 
Note: & The buffer contains mapping information and must have been prepared by a pre- 


vious call to Int 67H Function 4FH Subfunction 00H. 


Int 67H [EMS 4.0] 
Function 4FH (79) Subfunction 02H 
Get size of partial page map information 


Returns the size of the buffer which will be required to receive partial page-mapping information using 
Int 67H Function 4FH Subfunction 00H. 


Call with: AH = 4FH 
AL = 02H 
BX = number of pages 
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Returns: If function successful 
AH = 0OH 
AL = size of array (bytes) 
If function unsuccessful 
AH = error code 


Int 67H [EMS 4.0] 
Function 50H (80) Subfunction 00H 
Map multiple pages by number 


Maps one or more of the logical expanded memory pages assigned tc toa handle onto o physical memory 
pages that can be accessed by the CPU. Physical pages are referenced by their numbers. 


Callwith: AH = 50H 
AL = 00H 
CX = number of pages to map 
DX = EMM handle 
DS:SI = segment:offset of buffer (see Note) 
Returns: If function successful 
AH = 00H 
If function unsuccessful 
AH = error code 
Note: ™ The buffer contains a series of DWORD (32-bit) entries that control the pages to be 


mapped. The first word of each entry contains the logical expanded memory page 
number, and the second word contains the physical page number to which it should 
be mapped. If the logical page is —1, the physical page is unmapped (made inacces- 
sible for reading or writing). 


Int 67H [EMS 4.0] 
Function 50H (80) Subfunction 01H 
Map multiple pages by address 


Maps one or more of the logical expanded memory pages assigned t toa handle « onto © physical memory 
pages that can be accessed by the CPU. Physical pages are referenced by their segment addresses. 
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Call with: AH = 50H 


AL = 01H 

CX = number of pages to map 

DX = EMM handle 

DS:SI = segment:offset of buffer (see Notes) 


Returns: If function successful 
AH = 00H 
If function unsuccessful 
AH = error code 


Notes: # The buffer contains a series of DWORD (32-bit) entries that control the pages to be 
mapped. The first word of each entry contains the logical page number, and the sec- 
ond word contains the physical page segment address to which it should be mapped. 
If the logical page is -1, the physical page is unmapped (made inaccessible for read- 
ing or writing). 

a The mappable segment addresses may be obtained by calling Int 67H Function 58H 
Subfunction OOH. 


Int 67H [EMS 4.0] 
Function 51H (81) 
Reallocate pages for handle 


Modifies the number of expanded memory pages allocated to an EMM handle. 


Call with: AH = 51H 
BX = new number of pages 
DX = EMM handle 
Returns: If function successful 
AH = OOH 
BX = logical pages owned by EMM handle 
If function unsuccessful 
AH = error code 
EE 
Note: ™ If the requested number of pages is zero, the handle is still active, and pages can be 


reallocated to the handle at a later time; also, the handle must still be released with 
Int 67H Function 45H before the application terminates. 
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Int 67H [EMS 4.0] 
Function 52H (82) Subfwnction 00H 
Get handle attribute 


Returns the attribute (volatile or nonvolatile) associated with the specified handle. A nonvolatile memory 
handle and the contents of the expanded memory pages that are allocated to it are maintained across a 
warm boot operation (system restart using Ctrl-Alt-Del). 


Call with: AH = 52H 
AL = 00H 
DX = EMM handle 
Returns: If function successful 
AH = 00H 
AL = attribute 
O = volatile 
1 = nonvolatile 
If function unsuccessful 
AH = error code 


Int 67H 
Function 52H (82) Subfunction 01H 
Set handle attribute 


Sets the attribute (volatile or nonvolatile) associated with the specified handle. A nonvolatile memory 
handle and the contents of the expanded memory pages that are allocated to it are maintained across a 
warm boot operation (system restart using Ctrl-Alt-Del). 


Call with: AH = 52H 
AL = 01H 
BL = attribute 
O = volatile 
1 = nonvolatile 
DX = EMM handle 
Returns: If function successful 
AH = 00H 
If function unsuccessful 
AH = error code 
Note: m Ifthe expanded memory hardware cannot support nonvolatile pages, this function 


returns an error. 
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Int 67H [EMS 4.0] 
Function 52H (82) Subfunction 02H 
Get attribute capability 


Returns a code indicating whether the Expanded Memory Manager and hardware can support the non- 
volatile attribute for EMM handles. 


Call with: AH = 52H 
AL = 02H 


Returns: If function successful 


AH = 00H 
AL = attribute capability 
O = only volatile handles supported 
1 = volatile and nonvolatile handles supported 


If function unsuccessful 
AH = error code 


Int 67H [EMS 4.0] 
Function 53H (83) Subfunction 00H 
Get handle name 


Returns the 8-character name assigned to a handle. 


Call with: AH = 53H 

AL = 00H 

DX = EMM handle 

ES:DI = segment:offset of 8-byte buffer 
Returns: If function successful 

AH = 00H 


and name for handle in specified buffer 


If function unsuccessful 
AH = error code 


Note: # A handle’s name is initialized to 8 zero bytes when it is allocated or deallocated. 
Another name may be assigned to an active handle with Int 67H Function 53H 
Subfunction 01H. The bytes in a handle name need not be ASCII characters. 
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Int 67H 
Function 53H (83) Subfunction 01H 
Set handle name 


[EMS 4.0] 


Assigns a name to an EMM handle. 


Call with: AH = 53H 
AL = 01H 
DX = EMM handle 
DS:SI = segment:offset of 8-byte name 
Returns: If function successful 
AH = 00H 
If function unsuccessful 
AH = error code 
Notes: & The bytes in a handle name need not be ASCII characters, but the sequence of 8 


zero bytes is reserved for no name (the default after a handle is allocated or deallo- 
cated). A handle name should be padded with zero bytes, if necessary, to a length of 
8 bytes. 

# A handle may be renamed at any time. 


m= All handle names are initialized to 8 zero bytes when the system is turned on. The 
name of a nonvolatile handle is preserved across a warm boot. (See Int 67H Func- 
tion 52H Subfunctions 00H and 02H.) 


Int 67H [EMS 4.0] 
Function 54H (84) Subfunction 00H 
Get all handle names 


Returns the names for all active handles. 


Call with: AH = 54H 

AL = 00H 

ES:DI = segment:offset of buffer (see Notes) 
Returns: If function successful 

AH = 00H 

AL = number of active handles 


and buffer filled in with handle-name information (see Notes) 


If function unsuccessful 
AH = error code 
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Notes: The function fills the buffer with a series of 10-byte entries. The first 2 bytes of each 
entry contain an EMM handle, and the next 8 bytes contain the name associated with 
the handle. Handles that have never been assigned a name have 8 bytes of 0 as a 
name. 


# Because there is a maximum of 255 active handles, the buffer need not be longer 
than 2550 bytes. 


Int 67H [EMS 4.0] 
Function 54H (84) Subfunction 01H 


Search for handle name 


Returns the EMM handle associated with the specified name. 


Call with: AH = 54H 
AL = 01H 
DS:SI_ = = segment: offset of 8-byte handle name 


Returns: If function successful 


AH = 00H 

DX = EMM handle 
If function unsuccessful 
AH = error code 


Int 67H 
Function 54H (84) Subfunction 02H 

Get total handles 

Returns the total auinbee i handles that aie sisnanee by the Expanded Memory Mananer including the 
operating-system handle (0). 


[EMS 4.0] 


Call with: AH = 54H 
AL = 02H 
Returns: If function successful 
AH = 0OH 
BX = number of handles 


If function unsuccessful 
AH = error code 
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Int 67H [EMS 4.0] 
Function 55H (85) Subfunctions 00H and 01H 
Map pages and jump 


Alters the expanded memory mapping context and transfers control to the specified address. 


Call with: AH = 55H 
AL = subfunction 
O = map using physical page numbers 
1 = map using physical page segments 
DX = EMM handle 
DS:SI = segment:offset of buffer (see Notes) 
Returns: If function successful 
AH = 00H 
If function unsuccessful 
AH = error code 
Notes: =m The buffer contains map-and-jump entries in the following format: 
Offset Length Description 
00H 4 far pointer to jump target 
04H 1 number of pages to map before jump 
05H 4 far pointer to map list see below) 


The map list in turn consists of DWORD (32-bit) entries, one per page. The first word 
of each entry contains the logical page number, and the second word contains the 
physical page number or segment (depending on the value in register AL) to which it 
should be mapped. 

m= A request to map zero pages and jump is not considered an error, the effect is a 
simple far jump. 


Int 67H [EMS 4.0] 
Function 56H (86) Subfunctions 00H and 01H 
Map pages and call 


Alters the expanded memory mapping context and performs a far call to the specified address. When the 
destination routine executes a far return, the EMM again alters the page-mapping context as instructed 
and then returns control to the original caller. 
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Call with: AH = 56H 


AL = subfunction 
O = map using physical page numbers 
1 = map using physical page segments 
DX = EMM handle 
DS:SI = segment:offset of buffer (see Notes) 
Returns: If function successful 
AH = 00H 
If function unsuccessful 
AH = error code 
Notes: m= The format of the buffer containing map and call information is: 
Offset Length Description 
00H 4 far pointer to call target 
04H 1 number of pages to map before call 
05H 4 far pointer to list of pages to map before call (see below) 
09H 1 number of pages to map before return 
OAH 4 far pointer to list of pages to map before return (see below) 
OEH 8 reserved (0) 


Both map lists have the same format and consist of a series of double-word entries, 
one per page. The first word of each entry contains the logical page number, and the 
second word contains the physical page number or segment (depending on the value 
in register AL) to which it should be mapped. 


= A request to map zero pages and call is not an error; the effect is a simple far call. 


w This function uses extra stack space to save information about the mapping context; 
the amount of stack space required can be determined by calling Int 67H Function 
56H Subfunction 02H. 


Int 67H [EMS 4.0] 
Function 56H (86) Subfunction 02H 
Get stack space for map page and call 


Returns the number of bytes of stack space required by Int 67H Function 56H Subfunction 00H or 01H. 


Cail with: AH = 56H 
AL = 02H 
Returns: If function successful 
AH = 00H 
BX = stack space required (bytes) 


If function unsuccessful 
AH = error code 
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Int 67H [EMS 4.0] 
Function 57H (87) Subfunction 00H 
Move memory region 


Copies a memory region from any location in conventional or expanded memory to any other location 
without disturbing the current expanded memory mapping context. 


Call with: AH = 57H 
AL = 00H 
DS:SI = segment:offset of buffer (see Notes) 
Returns: If function successful 
AH = 00H 
If function unsuccessful 
AH = error code 
Notes: @ The format of the buffer controlling the move operation is: 
Offset Length Description 
00H 4 region length in bytes 
04H 1 source memory type (0 = conventional, 1 = expanded) 
05H 2 source memory handle 
07H 2 source memory offset 
09H 2 source memory segment or physical page number 
OBH 1 destination memory type (0 = conventional, 1 = expanded) 
0CH 2 destination memory handle 
OEH 2 destination memory offset 


10H 2 destination memory segment or physical page number 


@ A length of zero bytes is not an error. The maximum length of a move is 1 MB. If the 
length exceeds a single expanded memory page, consecutive expanded memory 
pages (as many as are required) supply or receive the data. 

If the source and destination addresses overlap, the move will be performed in such 


a way that the destination receives an intact copy of the original data, and a nonzero 
status is returned. 


Int 67H 
Function 57H (87) Subfunction 01H 
Exchange memory regions 


[EMS 4.0] 


Exchanges any two memory regions in conventional or expanded memory without disturbing the current 
expanded memory mapping context. 
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Call with: AH = 57H 


AL = 01H 
DS:SI = segment:offset of buffer (see Notes) 
Returns: If function successful 
AH = 00H 
If function unsuccessful 
AH = error code 
Notes: w The format of the buffer controlling the exchange operation is the same as for Int 


67H Function 57H Subfunction OOH. 


= An exchange of zero bytes is not an error. The maximum length of an exchange is 1 
MB. If the length exceeds a single expanded memory page, consecutive expanded 
memory pages (as many as are required) supply or receive the data. 

If the source and destination addresses overlap, the exchange is not performed and 
an error is returned. 


Int 67H [EMS 4.0] 
Function 58H (88) Subfunction 00H 


Get addresses of mappable pages 


Returns the segment base address and physical page number for each mappable page in the system. 


Call with: AH = 58H 
AL = 00H 
ES:DI = segment:offset of buffer (see Notes) 
Returns: If function successful 
AH = 00H 
CX = number of entries in mappable physical page array 


and page number/address information in buffer (see Notes) 


If function unsuccessful 
AH = error code 


Notes: @ Upon return from the function, the buffer contains a series of double-word entries, 
one per mappable page. The first word of an entry contains the page’s segment base 
address, and the second contains its physical page number. The entries are sorted in 
order of ascending segment addresses. 


m The size of the buffer required can be calculated with the information returned by 
Int 67H Function 58H Subfunction 01H. 
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Int 67H [EMS 4. 0] 
Function 58H (88) Subfunction 01H 
Get number of mappable pages 


Returns he aunbee of eae ae pages. 


Call with: AH = 58H 
AL =01H 
Returns: If function successful 
AH = 00H 
CX = number of mappable physical pages 
If function unsuccessful 
AH = error code 
Note: @ The information returned by this function can be used to calculate the size of the 


buffer that will be needed by Int 67H Function 58H Subfunction 00H. 


Int 67H [EMS 4.0] 
Function 59H (89) Subfunction 00H 
Get hardware configuration 


Returns information about the configuration of the expanded memory hardware. 


Call with: AH = 59H 

AL = 00H 

ES:DI = segment:offset of buffer (see Notes) 
Returns: If function successful 

AH = 00H 


and hardware configuration information in buffer. 


If function unsuccessful 
AH = error code 


Notes: & Upon return from the function, the buffer has been filled in with hardware configu- 
ration information in the following format: 
Offset Length Description 


00H 2 size of raw expanded memory pages (in paragraphs) 
02H 2 number of alternate register sets 
04H 2 size of mapping-context save area (in bytes) 
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Offset Length Description 


06H 2 number of register sets that can be assigned to DMA 
channels 
08H 2 DMA operation type (0 = DMA may be used with alternate 


register sets; 1 = only one DMA register set available) 


™ The size returned for the mapping-context save area is the same as the size returned 
by Int 67H Function 4EH Subfunction 03H. 


™ This function is intended for use by operating systems only and can be disabled by 
the operating system at any time. 


Int 67H [EMS 4.0] 
Function 59H (89) Subfunction 01H 
Get number of raw pages 


Obtains the total number of raw expanded memory pages present in the system and the number of raw 
pages that are not already allocated. Raw memory pages may have a size other than 16 KB. 


Call with: AH = 59H 
AL = 01H 
Returns: If function successful 
AH = 00H 
BX = unallocated raw pages 
DX = total raw pages 
If function unsuccessful 
AH = error code 
Note: m™ Ifthe Expanded Memory Manager supports only pages of standard size; the values 


returned by this function are the same as those returned by Int 67H Function 42H. 


Int 67H [EMS 4.0] 
Function 5AH (90) Subfunction 00H 
Allocate handle and standard pages 


Allocates an EMM handle and associates standard (16 KB) expanded memory pages with that handle. 


Call with: AH = 5AH 
AL = 00H 
BX = number of standard pages to allocate 
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Returns: If function successful 
AH = 00H 
DX = EMM handle 
If function unsuccessful 
AH = error code 


Note: @ Unlike Int 67H Function 43H, allocating zero pages with this function is not an error. 


Int 67H [EMS 4.0] 
Function 5AH (90) Subfunction 01H 
Allocate handle and raw pages 


Allocates a raw EMM handle and associates raw expanded memory pages with that handle. 


Call with: AH = 5AH 

AL = 01H 

BX = number of raw pages to allocate 
Returns: If function successful 

AH = 00H 

DX = handle for raw EMM pages 

If function unsuccessful 

AH = error code 
Notes: = Raw memory pages may have a size other than 16 KB. 


@ Allocation of zero pages is not an error. 


Int 67H [EMS 4.0] 
Function 5BH (91) Subfunction 00H 
Get alternate map registers 


Returns the number of the active alternate register set or, if no alternate set is active, saves the state of the 
mapping registers into a buffer and returns its address. 


Call with: AH = 5BH 
AL = OOH 
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Returns: If function successful and alternate map register set active 


AH = 00H 
BL = current active alternate map register set 
If function successful and alternate map register set not active 
AH = 00H 
BL = 00H 
ES:DI = segment:offset of alternate map register save area (if BL = 0) 
If function unsuccessful 
AH = error code 
Notes: ™ The address of the save area must have been specified in a previous call to Int 67H 


Function 5BH Subfunction 01H, and the save area must have been initialized by a 
previous call to Int 67H Function 4EH Subfunction OOH. If there was no previous call 
to Int 67H Function 5BH Subfunction 01H, the address returned is zero, and the 
registers are not saved. 


@ This function is intended for use by operating systems only and can be disabled by 
the operating system at any time. 


Int 67H [EMS 4.0] 
Function 5BH (91) Subfunction 01H 
Set alternate map registers 


Selects an alternate map register set or (if alternate sets are not supported) restores the mapping context 
from the specified buffer. 


Call with: AH = 5BH 

AL = 01H 

BL = alternate register set number or OOH 

ES:DI = segment:offset of map register context restore area (if BL = 0) 
Returns: If function successful 

AH = 00H 

If function unsuccessful 

AH = error code 
Notes: ™ The buffer address specified in this call is returned by subsequent calls to Int 67H 


Function 5BH Subfunction 00H with BL = 00H. 


™ The save area must have been initialized by a previous call to Int 67H Function 4EH 
Subfunction 00H. 


® This function is intended for use by operating systems only and can be disabled by 
the operating system at any time. 
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Int 67H [EMS 4. 0] 
Function 5BH (91) Subfunction 02H 
Get size of alternate map register save area 


Returns the amount of storage needed by Int 67H Function SBH ( Subfunctions 0 00H {and 0 01H. 


Call with: AH = 5BH 
AL = 02H 
Returns: If function successful 
AH = 00H 
DX = size of buffer (bytes) 
If function unsuccessful 
AH = error code 
Note: ® This function is intended for use by operating systems only and can be disabled by 


the operating system at any time. 


Int 67H [EMS 4. 0} 
Function 5BH (91) Subfunction 03H 
Allocate alternate map register set 


Allocates an alternate | map register set for use with Int 67H. Function n SBH Subfunctions 0 00H and 0 01H. T The 
contents of the currently active map registers are copied into the newly allocated alternate map registers 
in order to provide an initial context when they are selected. 


Call with: AH = 5BH 
AL = 03H 
Returns: If function successful 
AH = 00H 
BL = alternate map register set number or zero, if no alternate 


sets are available 


If function unsuccessful 
AH = error code 


a —————————— 


Note: ™ This function is intended for use by operating systems only and can be disabled by 
the operating system at any time. 
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Int 67H [EMS 4.0] 
Function 5BH (91) Subfunction 04H 
Deallocate alternate map register set 


Releases an alternate map register set that was previously allocated with Int 67H Function 5BH Subfunc- 
tion 03H. 


Call with: AH = 5BH 
AL = 04H 
BL = alternate register set number 


Returns: If function successful 
AH = 00H 
If function unsuccessful 
AH = error code 


Notes: = The current alternate map register set cannot be deallocated. 
= This function is intended for use by operating systems only and can be disabled by 
the operating system at any time. 


Int 67H | [EMS 4.0] 
Function 5BH (91) Subfunction 05H 
Allocate DMA register set 


Allocates a DMA register set. 


Call with: AH = 5BH 
AL = 05H 


Returns: If function successful 
AH = 00H 
BL = DMA register set number (0 = none available) 
If function unsuccessful 
AH = error code 


COO ---rvwmY—“——— SSS 


Note: a This function is intended for use by operating systems only and can be disabled by 
the operating system at any time. 


642 = Section IV 


’ 


Int 67H 
Function 5BH (91) Subfunction 06H 
Enable DMA on alternate map register set 


[EMS 4.0] 


Associates a DMA channel with an alternate map register set. 


Call with: AH = 5BH 
AL = 06H 
BL = alternate map register set 
DL = DMA channel number 
Returns: If function successful 
AH = 00H 
If function unsuccessful 
AH = error code 
Notes: = Ifa DMA channel is not assigned to a specific register set, DMA for that channel will 


be mapped through the current register set. 

= If zero is specified as the alternate map register set, no special action is taken on 
DMA accesses for the specified DMA channel. 

m This function is intended for use by operating systems only and can be disabled by 
the operating system at any time. 


Int 67H [EMS 4.0] 
Function 5BH (91) Subfunction 07H 
Disable DMA on alternate map register set 


Disables DMA accesses for all DMA channels associated with a specific alternate map register set. 


Call with: AH = 5BH 

AL = 07H 

BL = alternate register set number 
Returns: If function successful 

AH = 00H 

If function unsuccessful 

AH = error code 
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Note: # This function is intended for use by operating systems only and can be disabled by 
the operating system at any time. 


Int 67H [EMS 4.0] 
Function 5BH (91) Subfunction 08H 
Deallocate DMA register set 


Deallocates a DMA register set that was previously allocated with Int 67H Function SBH Subfunction 05H. 


Call with: AH = 5BH 
AL = 08H 
BL = DMA register set number 
Returns: If function successful 
AH = 00H 
If function unsuccessful 
AH = error code 
Note: = This function is intended for use by operating systems only and can be disabled by 


the operating system at any time. 


Int 67H [EMS 4.0] 
Function 5CH (92) 
Prepare Expanded Memory Manager for warm boot 


Prepares the expanded memory hardware for an impending warm boot. This function affects the current 
mapping context, the alternate register set in use, and any other expanded memory hardware dependen- 
cies that would ordinarily be initialized at system boot time. 


Call with: AH = 5CH 
Returns: If function successful 
AH = 00H 
If function unsuccessful 
AH = error code 
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Note: a If an application maps expanded memory at addresses below 640 KB, the applica- 
tion must trap all possible conditions that might lead to a warm boot, so that this 
function can be called first. 


Int 67H [EMS 4. 0] 
Function 5DH (93) Subfunction 00H 
Boar? EMM operating: ayniem rctons: 


Enables the operating- sai een) EMM panctions Cnt 67H Functions 5 59H, SBH, and 1 5DH) f for ails 
by any program or device driver. (This is the default condition.) 


Call with: AH = 5DH 
AL = 00H 
BX:CX = access key Cif not first call to function) 


Returns: If function successful 
AH = 00H 
BX:CX = access key Cif first call to function) 
If function unsuccessful 
AH = error code 


Notes: ™ Anaccess key is returned in registers BX and CX on the first call to Int 67H Function 
5DH Subfunction 00H or 01H. The access key is required for all subsequent calls to 
either function. 


™ This function is intended for use by operating systems only. 


Int 67H [EMS 4. 0} 
Function 5DH (93) Subfunction 01H 
Disable EMM operating eynetn senna 


Disibies the Scene ee ane EMM eee int 67H Functions 50H, SBH, ne SDH)! for an. 
by application programs and device drivers, reserving the use of these functions for the operating 
system. 


Call with: AH = 5DH 
AL = 01H 
BX:CX = access key (if not first call to function) 
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Returns: If function successful 
AH = 0OH 
BX:CX = access key Cif first call to function) 
If function unsuccessful 
AH = error code 


Notes: = An access key is returned in registers BX and CX on the first call to Int 67H Function 
5DH Subfunction 00H or 01H. The access key is required for all subsequent calls to 
either function. 


= This function is intended for use by operating systems only. 


Int 67H [EMS 4.0] 
Function 5DH (93) Subfunction 02H 
Release access key 


Releases the access key obtained by a previous call to Int 67H Function 5DH Subfunction 00H or 01H. 


Call with: AH = 5DH 
AL = 02H 
BX:CX = access key 


Returns: If function successful 


AH = 00H 

If function unsuccessful 

AH = error code 
eee 
Notes: = With respect to the operating-system—specific expanded memory functions, the 


EMM is returned to the state it had when the system was initialized. A new access 
key is returned by the next call to Int 67H Function 5DH Subfunction 00H or 01H. 


™ This function is intended for use by operating systems only and can be disabled by 
the operating system at any time. 
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< 298-99 

> 298-99 
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86-DOS operating system 4 
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Absolute disk read 482-84 
Absolute disk write 484-85 
adapters, video display 86-87 
alarm 
reset 592 
set 591-92 
align type 38 
Allocate alternate map register set (EMS) 
641 
Allocate DMA register set (EMS) 642 
Allocate handle and pages (EMS) 617-18 
Allocate handle and raw pages (EMS) 639 
Allocate handle and standard pages 
(EMS) 638-39 
Allocate memory block 438-39 
ANSLSYS device driver, screen control 91 
escape sequences used with 92—93 
APPEND 490-91 
application program interface (API) 320 
application programs. See MS-DOS 
application programs, porting to 
OS/2; MS-DOS application 
programs, structure of; MS-DOS 
application programs, writing 
compatible 
arena entries 196 
arena headers 196, 201 
diagram example 202 
ASCII escape code 92—93 
ASCII mode 69 
character-device drivers in 261-62 
ASCII text files 56 
ASCIIZ strings 24, 139, 168 


.ASM files 45. See also assembly-language 
programs 
assembly-language programs 37—42 
to access file allocation table 197 
BREAK.ASM 75-78 
CLEAN.ASM 304-9 
DRIVER.ASM 283-91 
DUMP.ASM 152-61 
HELLO.COM example 27-30, 33-36 
program modules 37 
program procedures 41—42 
program segments 38—41 
PROTO.ASM 301-2 
SHELL.ASM program 229-38 
TALK.ASM 113-26 
ZERODIV.ASM 254, 255—58 
ASSIGN 489 
ASSUME statement 29, 33 
attribute byte 
color text display 98 
monochrome text display 97 
attribute word, device 264 
Auxiliary device (AUX) 12, 106, 298. See 
also serial port 
Auxiliary input 344-45 
Auxiliary output 345—46 


5 


background, set 508-9 

BACKUP command 15 

BAT (batch) files 15 

Batch files 15 

binary mode 69 
character-device drivers in 261-62 
output 93-94 

BIOS module 12-13, 17 
get address of extended, 574 

BIOS parameter block (BPB) 181, 189 
build 272 
structure 269 

bit planes 101 

blink/intensity bit, toggle 513 

block-device drivers 260, 262 
check for remoteness 423—24 
check removability of 422-23 
generic I/O control of 429-32 
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block-device drivers, continued 
read control data from 418-19 
write control data to 419-20 
Boot disk device (block device) 12 
boot drive, get 392-93 
boot sector, disk 179-82 
map of 180 
partial disassembly of 182 
partial hex dump 181 
bootstrap routine 16, 17 
border 
get color 514 
get palette and 514 
set 508-9 
set color 512 
BREAK.ASM program 75—78 
break flag, get or set 392-93 
Buffered keyboard input 351-52 
Build BIOS Parameter Block (function 
02H) 272 . 


C 


CALL instructions 41 
Cancel device redirection 467-68 
cassette motor 
read 561 
turn off 560-61 
turn on 560 
write 562 
C files 45. See also C language 
Change sharing retry count 425-26 
character blocks, set specifier 520 
character-device drivers 260, 261-62 
ASCII us binary mode 261—62 
generic I/O control 426-29 
read control data from 415-16 
write control data to 416-17 
character input/output. See also keyboard 
input, mouse, input; pointing 
device, input; printer output; serial 
port 
Int 21H 44H IOCTL (I/O control) 
411-43 
Int 21H functions, summary 337-38 
(table) — 
processing typical I/O request 281-82 
Character input with echo 343 
Character input without echo 349-50 
Character output 344 
CHDIR (CD) command 167 
Check if block device is remote 423-24 
Check if block device is removable 
422-23, 
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Check if handle is remote 424-25 
Check input status 353, 420-21 
Check output status 421-22 
child programs 218 
CHKDSK command 15, 174, 222 
C language 
CLEAN.C 309-11 
compiler (see C Optimizing Compiler) 
DUMP.C program 151, 161-63 | 
linking Ctrl-C and Ctrl-Break handlers 
to programs in 75-80 
MOUDEMO.C 82-83 
polling mouse and displaying mouse 
coordinates 82-83 
PROTO.C 303 
SHELL.C 225-29 
TRYBREAK 78-79 
tutorials 63 
class type 38 
CLEAN filter 303-11 
assembly source code 304~9 
C source code 309-11 
clock, set tick count 589-90 
CLOCK driver 282 
Close file 357-58, 404-5 
code page, get or set 474-75 
code segment 38 
code segment (CS) register 30 
Color/Graphics Adapter (CGA) 86, 
98, 102 
color page state 
get 517 
set 515-16 
color register(s) 
get 516 
get block of 516-17 
set 514-15 
set block of 515 
COM1, COM2, COM3 devices 106, 
110-12, 298 
combine type 38 
command code routines, device-driver 
267-81 
function 00H, Driver initialization 
268-69 
function 01H, Media Check 270-71 
function 02H, Build BIOS Parameter 
Block (BPB) 272 
function 03H, I/O-Control Read 
272-73 
function 04H, Read 273 
function 05H, Nondestructive Read 274 
function 06H, Input Status 274 


command code routines, continued 
function 07H, Flush Input Buffers 
274-75 
function 08H, Write 275 
function 09H, Write with Verify 276 
function OAH, Output Status 276 
function OBH, Flush Output Buffers 
276 
function OCH, I/O-Control Write 
276-77 
function ODH, Device Open 277 
function 0EH, Device Close 277-78 
function OFH, Removable Media 278 
function 10H, Output Until Busy 
278-79 
function 13H, Generic IOCTL 279-80 
function 17H, Get Logical Device 280 
function 18H, Set Logical Device 
280-81 
names of, and MS-DOS version support 
267-68 (table) 
COMMAND.COM file 14-16 
load 20 
replacing 13 
use of EXEC function 218 
COMMAND.COM PLUS 13 
command processor (shell) 13. See also 
COMMAND.COM file 
commands, types of, accepted by 
COMMAND.COM 14-15 
command tail 24, 220-21 
Commit file 476-77 
compatibility and portability 313-31 
degrees of compatibility 314-18 
MS-DOS applications 315-17 
ROM BIOS and hardware- 
compatible applications 317-18 
OS/2 compatibility 318-31 
.COM program file(s) 15, 22, 25-30, 45 
assembly-language program 
transformed into 27—30 
vs EXE files 22, 36 (table) 
memory allocation for 197-98 
memory image of a typical 26 
CONFIG.SYS file 12 
installing device driver 293 
opening 18-19 
configuration 
get equipment 535-36 
get information 525 
get system environment 573-74 
console, direct input/output 347—48. See 
also video display 


Console display and keyboard (CON) 12, 
298-99 
control data 
read, from block-device driver 418-19 
read, from character-device driver 
415-16 
write, to block-device driver 419-20 
write, to character-device driver 
416-17 
Controller drive diagnostic 551 
Controller internal diagnostic 551 
Controller RAM diagnostic 550 
cooked mode 69 
C Optimizing Compiler 44, 48-50 
environmental variables 48 
version 5.1 switches 49—50 
COPY command 14, 58 
Country information 
get extended 470-74 
get or set 395-98 
CP/M operating system 4, 5 
FCB compatibility with 129, 130-31 
program segment prefix compatibility 
with 24, 25 
Create directory 398-99 
Create file 364—65, 401-2 
Create new file 458-59 
Create new PSP 378-79 
Create temporary file 457-58 
CREF utility 44, 56-58 
cross-reference listing for HELLO.REF 
D7 
.CRF files 45, 56 
Critical-error handler address 481-82 
critical-error handlers 24, 145, 147-51 
address 481-82 
skeleton program example 150—51 
stack at entry to 148, 749 
cross-reference listing. See CREF utility 
Ctrl-Break and Ctrl-C handlers 72—80 
compatibility issues 317 
Ctrl-C handler address 480-81 
high-level languages and 75-80 
cursor 
addressing 97 
enable/disable emulation 528 
get position 502-3 
read character and attribute at 506 
set position 501—2 
set type 501 
write character and attribute at 506-7 
write character at 507-8 
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data segment 38 
data segment (DS) register 31, 35 
Date and time device (CLOCK$) 12 
day count 
get 592-93 
set 593 
Deallocate alternate map register set 
(EMS) 642 
Deallocate DMA register set (EMS) 644 
.DEF files 45 
Delay 568-69 
DEL(ETE) command 14 
Delete directory 399 
Delete file 361-62, 407-8 
dependency statements 61 
descriptors, memory segment 321 
device 
cancel redirection 467-68 
close 565 
get device information 412-13 
open 564-65 
post 572-73 
read file or 405-6 
redirect 466-67 
set device information 414-15 
wait 571 
write file or 406-7 
Device Close (command code function 
OEH) 277-78 
Device close (MS-DOS function) 565 
DEVICE commands 12 
device drivers, installable 12-13, 259-96 
CLOCK driver 282 
command-code routines 267-81 
debugging 295-96 
chain before/after driver installation 
294 
chain listing 295 
device attribute word 264 
error codes 267 
MS-DOS type 260-63 
processing of typical input/output 
requests 281-82 
structure of MS-DOS 263-67 
device header 263-64 
interrupt routine 266-67 
strategy routine 265 
writing and installing 282-95 
assembly 283-92 
installation 293-95 
linking 293 
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device drivers, resident 12-13 
Device Open (command-code function 
QODH) 277 
Device open (MS-DOS function) 564-65 
Device post 572-73 
Device wait 571-72 
Digital Research 4 
DIR command 14, 167, 174 
Direct console I/O 347—48 
directory 166, 167-73 
create 398-99 
delete 399 
format of a single entry in a disk 
184, 185 
functions controlling 167-68 
get current 437-38 
hierarchical (tree) structure 166, 167 
moving files 173 
root 184-86 
searching 168-73 
set current 400 
directory operations, Int 21H functions 
summary 339 
Disable DMA on alternate map register 
set (EMS) 643-44 
Disable EMM operating system functions 
(EMS) 645-46 
Disable mouse driver 608-~9 
disk(s) 177-94. See also drive, logical, 
ESDI Fixed Disk Drive Adapter 
absolute read 482-84 
absolute write 484-85 
boot sector 179-82 
controller drive diagnostic 551 
controller internal diagnostic 551 
controller RAM diagnostic 550 
file allocation table 182-84 
interpreting the 188-92 
files area 186-88 
fixed-disk partitions 192~—94 
format 543 
format bad track 542 
format track 541—42 
get change status 552-53 
get current 367 
get default drive data 368-69 
get drive allocation information 
394-95 
get drive data 370 
get drive parameters 543—44 
get drive status 549 
get type 552 
initialize fixed disk characteristics 


544-45 


disk(s), continued 
map of typical logical volume 179 
park heads 554-55 
read sector 538-39 
read sector buffer 548 
read sector long 545-46 
recalibrate 550 
reserved area 182 
reset 354-55 
reset fixed disk system 548 
root directory 184-86, 187 
seek 547 
select 355-56 
set media type 554 
set type 553 
set verify flag 387-88 
verify sector 540 
write sector 539-40 
write sector buffer 549 
write sector long 546—47 
disk bootstrap routine 16 
memory location of 77 
disk management, Int 21H functions 
summary 339 
disk-related errors 147, 148 (table) 
Disk reset 354-55 
disk system 
get status 537-38 
reset 536-37 
disk transfer area (DTA) 25, 130 
get 388-89 
set 368 
display page, set 503—4 
Display string 350—51 
DOS kernel 12, 18 
memory location of 19 
double-byte character sets (DBCS), get 
lead byte table 469-70 
drive, logical 166, 167-73. See also disk(s) 
get map 433 
set map 434 
vs volume 174 
driver. See device drivers, installable; 
device drivers, resident 
DRIVER.ASM program 283-91 
Driver Initialization (function 00H) 
268-69 
DUMP.ASM program 151, 152-61 
subroutines 163 
DUMP.C program 151, 161-63 
Duplicate handle 435 
dynamic link library 331 
dynamic memory allocation 199, 200, 201 
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echo 
character input with 343 
character input without 349-50 
unfiltered character input without 
348-49 
EMS. See Expanded Memory 
Specification CEMS) 
Enable/disable cursor emulation 528 
Enable/disable default palette loading 
526-27 
Enable/disable gray-scale summing 527 
Enable/disable pointing device 574-75 
Enable/disable screen refresh 529 
Enable/disable video 527 
Enable DMA on alternate map register 
set (EMS) 643 
Enable EMM operating system functions 
(EMS) 645 
Enable mouse driver 609 
encapsulation of subroutines 323, 
324-25 
end of interrupt CEOD) 250 
ENDP command 35, 41 
ENDS command 29, 38 
END statement 30-31, 36, 41 
Enhanced Graphics Adapter (EGA) 86, 
97, 98, 102 
Enter protected mode 570-71 
environment block 24, 220, 224-25 
dump of a typical 224 
three strings contained in 225 
EQU statement 33 
error codes, device driver 267 
error codes, MS-DOS 145-51 
critical 145, 147-51 
expanded memory 207-9 
error information, get/set 453-56 
escape sequences, ANSI 92-93 
ESDI Fixed Disk Drive Adapter 
format drive 555 
format periodic interrupt 562-63 
Event wait 566-67 
Exchange memory regions (EMS) 635-36 
EXE2BIN utility 44, 55-56 
EXEC function 15, 217—42. See also Int 
21H Function 4BH 
calling convention 222 
compatibility in MS-DOS applications 
317 
environment block 220, 224-25 
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EXEC function, continued 
example programs SHELL.C and 
SHELL.ASM 225—40 
basic flow of both 239—40 
internal commands in 239 
example use of 223-24 
loading overlays with 240, 241-42 
making memory available for 218-19 
reference 441—42 
requesting 219-21 
returning from 221-24 
-EXE (executable) program file(s) 15, 22, 
30-36, 45 
assembly language program 
transformed into 33-36 
vs .COM files 22, 36 (table) 
converting, to .COM files (see EXE2BIN 
utility) 
header 30 
load module contents 33 
load module format 32 
memory allocation for 198 
memory image of 37 
use for compatible MS-DOS 
applications 315 
Expanded Memory Manager (EMM) 
203-4 
checking for 204, 205-6 
enable/disable system functions 
645-46 
error codes 207-9 
Expanded Memory Specification (EMS) 
201-11 : 
checking for expanded memory 204-6 
expanded memory defined 203-4 
functions reference (see Section IV) 
summary 614-15 
use of expanded memory 207-11 
skeleton program illustrating 210-11 
Extended communications port control 
559-60 
extended file control block 131 
volume-label search using 175 
Extended initialize communications port 
558-59 
extended memory 204, 212-15 
moving blocks of data between 
conventional memory and 213-15 
Extended open file 478-80 
external (extrinsic) commands 15 
external hardware interrupts 247 
extra segment (ES) register 31 
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FAR attribute 35 
vs NEAR 29 
faults (internal hardware interrupts) 246, 
321 
file(s) 
area, in disks 186-88 
close 357-58, 404 
commit 476-77 
create 364-65, 401-2 
create new 458-59 
create temporary 457-58 
delete 361-62, 407-8 
extended open 478-80 
find first 358-59, 445—46 
find next 360-61, 446-47 
get file size 375-76 
get/set date and time 450-51 
lock/unlock file region 460-61 
logical drive 166 
moving 123 
name and location 166 
open 356-57, 402—4 
read 405-6 
rename 366, 449-50 
types 45 
write 406-7 
file-access skeleton program 
using FCB functions 134, 135-37 
using handle functions 141, 142-43 
file allocation table (FAT) 166, 182-84 
assembly program to access 191 
contents 183 
interpreting 188-92 
media descriptor bytes 183 
file attributes, get or set 410-11 
file control blocks (FCBs) 25, 128 
default 130, 221 
directory searching with 169, 170-71 
extended 131, 133-34, 175 
file management with FCB functions 
129-39 
advantages/disadvantages 138-39 
file-access skeleton program 134-38 
functions listed 132 
vs handle functions 128 
normal 129, 133-34 
before/after open call (Int 21H 
Function OFH) 137 
restricted use 316, 319 
typical operation of 130 


file management 127-63 
example programs DUMP.ASM and 
DUMBP.C 151-63 
FCB functions 128, 129-39 
handle functions 128, 139-44 
MS-DOS error codes 145-51 
filename 
fully qualified 166 
parse 382-83 
requesting EXEC function 219 
file operations, Int 21H functions 
summary 338 
file pointer, set 408-9 
file system 166 
structure 167 
filters 297-311 
building 300-303 
CLEAN filter 303-11 
operation of 299-300 
prototype 301-3 
system support for 298-99 
Find first file 358-59, 445-46 
Find next file 360-61, 446-47 
fixed-disk partitions 192-94 
font functions 518-24 
Format bad track 542 
Format drive 543 
Format ESDI drive 555-56 
Format ESDI drive periodic interrupt 
562-63 
Format track 541-42 
Flush input buffer and then input 353-54 
Flush Input Buffers (function 07H) 
274-75 
Flush Output Buffers (function OBH) 276 


G 


Generic I/O control for block devices 
429-32 

Generic I/O control for character devices 
426-29 

Generic IOCTL (function 13H) 279-80 

Get addresses of mappable pages 
(EMS) 636 

Get address of alternate mouse event 
handler 606 — 

Get address of extended BIOS data 
area 574 

Get all handle names (EMS) 631 

Get alternate map registers (EMS) 
639-40 

Get attribute capability CEMS) 630 


Get block of color registers 516-17 

Get border color 514 

Get button press information 596 

Get button release information 597 

Get color page state 517 

Get color register 516 

Get communications port status 558 

Get configuration information 525 

Get conventional memory size 536 

Get current directory 437-38 

Get current disk 367 

Get cursor position 502-3 

Get date 384-85, 591 

Get day count 592 

Get DBCS lead byte table 469-70 

Get default drive data 368-69 

Get device information 412-13 

Get disk change status 552-53 

Get disk system status 537-38 

Get disk type 552 

Get drive allocation information 394-95 

Get drive data 370-71 

Get drive parameters 543-44 

Get drive status 549 

Get DTA address 388-89 

Get enhanced keyboard flags 586-87 

Get equipment configuration 535-36 

Get extended country information 
470-74 

Get extended error information 453-56 

Get extended memory size 570 

Get file size 375-76 

Get font information 524 

Get functionality/state information 
531-34 

Get handle attribute (EMS) 629 

Get handle count (EMS) 621-22 

Get handle name (EMS) 630 

Get handle pages (EMS) 622 

Get hardware configuration (EMS) 
637-38 

Get interrupt vector 393-94 

Get keyboard flags 582 

Get keyboard status 582 

Get language number 610 

Get light pen position 503 

Get Logical Device (command-code 
function) 280 

Get logical drive map 433 

Get machine name 461-62 

Get mouse information 611 

Get mouse position and button status 595 

Get mouse save state buffer size 603 
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Get mouse sensitivity 607 

Get MS-DOS version number 389-90 

Get number of mappable pages (EMS) 
637 

Get number of pages (EMS) 617 

Get number of raw pages (EMS) 638 

Get or set allocation strategy 452-53 

Get or set break flag, get boot drive 
392-93 

Get or set code page 474-75 

Get or set country information 395-98 

Get or set display combination code 
530-31 

Get or set file attributes 410-11 

Get or set file date and time 450-51 

Get page frame address (EMS) 616 

Get pages for all handles (EMS) 623 

Get palette and border 514 

Get palette register 513 

Get pointer page 608 

Get pointing device type 577 

Get printer setup string 463-64 

Get printer status 588 

Get PSP address 468-69 

Get redirection list entry 464—65 

Get return code 444—45 

Get size of alternate map register save 
area (EMS) 641 

Get size of page map information (EMS) 
625 

Get size of partial page map information 
(EMS) 626-27 

Get stack space for map page and call 
(EMS) 634 

Get status (EMS) 616 

Get system environment 573-74 

Get tick count 589 

Get time 386, 590 

Get total handles (EMS) 632 

Get verify flag 448 

Get version (EMS) 619 

Get video mode 511 

Graphics CardPlus 87 

graphics mode memory-mapped 
programming 101-3 

gray-scale 

enable/disable summing 527 
get values 517 
GROUP directive 39 
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handle functions 
check if handle is remote 424-25 
directory searching 169-70, 172-73 
DUMP.ASM program 151, 152-62 
DUMP.C program 151, 161-63 
duplicate handle 435 
file/record management with 139-44 
advantages/disadvantages 144 
vs FCB functions 128 
file access skeleton program 141—43 
functions listed 140-41 
typical operation 139 
keyboard input 62, 67-69 
redirect handle 436-37 
set handle count 475-76 
use for compatible MS-DOS 
applications 316 
volume-label search using 176 
hardware-compatible applications 
314-15, 317-18 
header 
device 263, 264, 269 
-EXE program files 30 
Hercules Graphics Card 87, 97, 98 
HELLO.COM program 27, 28-29, 30 
hex dump of 33 
map produced by Object Linker during 
generation of 57 
HELLO.EXE program 33, 34-35, 36 
HELLO.REF program, cross-reference 
listing 57 
H files 45 
Hide mouse pointer 595 


I 


IBMBIO.COM file 16 
disk location 189-92 
IBM Corporation, role in MS-DOS 
development 4-5 
IBMDOS.COM file 13, 16 
IBM PC 64 
PC/AT 64 
PS/2 64 
regen buffers in memory for various 
adapters 87 
“ill-behaved” applications 315 
.INC files 45 
In-Color Card 87 
Initialize communications port 556-57 
Initialize fixed disk characteristics 
544-45 


Initialize or scroll window down 505-6 
Initialize or scroll window up 505 
Initialize pointing device interface 
577-78 
Initialize printer port 587—88 
input. See character input/output, 
keyboard input; mouse, input, 
pointing device, input, serial port 
input buffer, flush 353-54 
Input/Output (I/O)-Control Read 
(function 03H) 272-73 
Input/Output (1/O)-Control Write 
(function OCH) 276-77 
input/output (I/O) redirection 67, 298-99 
input status, check 353, 420 
Input Status (command-code function 
06H) 274 
INS8250 Asynchronous Communications 
Controller 112 
installable device drivers 12-13 
Int 10H, ROM BIOS video driver 
Function 00H, Set video mode 94, 500 
Function 01H, Set cursor type 94, 501 
Function 02H, Set cursor position 
94,501 
Function 03H, Get cursor position 
94, 502 
Function 04H, Get light pen position 
95, 503 
Function 05H, Set display page 95, 503 
Function 06H, Initialize or scroll 
window up 95, 505 
Function 07H, Initialize or scroll 
window down 95, 505 
Function 08H, Read character and 
attribute at cursor 95, 506 
Function 09H, Write character and 
attribute at cursor 94, 506 
Function OAH, Write character at 
cursor 94, 507 
Function 0BH, Set palette, 
background, or border 95, 508 
Function 0CH, Write graphics pixel 
95, 509 
Function ODH, Read graphics pixel 
95, 510 
Function 0EH, Write character in 
teletype mode 94, 510 
Function OFH, Get video mode 94, 511 
Function 10H palette functions 
Subfunction 00H, Set palette register 
511 
Subfunction 01H, Set border color 
512 
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Subfunction 02H, Set palette and 
border 512-13 

Subfunction 03H, Toggle blink/ 
intensity bit 513 

Subfunction 07H, Get palette 
register 513 

Subfunction 08H, Get border color 
514 

Subfunction 09H, Get palette and 
border 514 

Subfunction 10H, Set color register 
514 

Subfunction 12H, Set block of color 
registers 515 

Subfunction 13H, Set color page state 
515-16 

Subfunction 15H, Get color register 
516 

Subfunction 17H, Get block of color 
registers 516 

Subfunction 1AH, Get color page 
state 517 

Subfunction 1BH, Set gray-scale 
values 517 

Function 11H, font functions 

Subfunctions 00H and 10H, Load 
user font 518 

Subfunctions 01H and 11H, Load 
ROM 8-by-14 font 518 

Subfunctions 02H and 12H, Load 
ROM 8-by-8 font 519 

Subfunction 03H, Set block specifier 
520 

Subfunctions 04H and 14H, Load 
ROM 8-by-16 font 520 

Subfunction 20H, Set Int 1FH font 
pointer 521 

Subfunction 21H, Set Int 43H for 
user’s font 522 

Subfunction 22H, Set Int 43H for 
ROM 8-by-14 font 522 

Subfunction 23H, Set Int 43H for 
ROM 8-by-8 font 523 

Subfunction 24H, Set Int 43H for 
ROM 8-by-16 font 523 

Subfunction 30H, Get font 
information 524 

Function 12H 

Subfunction 10H, Get configuration 
information 525 

Subfunction 20H, Select alternate 
printscreen 526 

Subfunction 30H, Set scan lines 526 
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Int 10H, Function 12H, continued 
Subfunction 31H, Enable/disable default 
palette loading 526-27 
Subfunction 32H, Enable/disable video 
527 
Subfunction 33H, Enable/disable gray- 
scale summing 527 
Subfunction 34H, Enable/disable cursor 
emulation 528 
Subfunction 35H, Switch active display 
528 
Subfunction 36H, Enable/disable screen 
refresh 529 
Function 13H, Write string in teletype 
mode 529 
Function 1AH, Get or set display 
combination code 530 
Function 1BH, Get functionality/state 
information 531 
Function 1CH, Save or restore video 
state 534 


Int 11H, Get equipment configuration 535 


Int 12H, Get conventional memory size 
536 
Int 13H, ROM BIOS disk driver 319 
Function 00H, Reset disk system 536 
Function 01H, Get disk system status 
537 
Function 02H, Read sector 538 
Function 03H, Write sector 539 
Function 04H, Verify sector 540 
Function 05H, Format track 541 
Function 06H, Format bad track 542 
Function 07H, Format drive 543 
Function 08H, Get drive parameters 
543 
Function 09H, Initialize fixed disk 
characteristics 544 
Function OAH, Read sector long 545 
Function OBH, Write sector long 546 
Function 0CH, Seek 547 


Function ODH, Reset fixed disk system 


548 
Function OEH, Read sector buffer 548 
Function OFH, Write sector buffer 549 
Function 10H, Get drive status 549 
Function 11H, Recalibrate drive 550 
Function 12H, Controller RAM 
diagnostic 550 
Function 13H, Controller drive 
diagnostic 551 
Function 14H, Controller internal 
diagnostic 551 
Function 15H, Get disk type 552 
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Int 13H, continued 
Function 16H, Get disk change status 
552 
Function 17H, Set disk type 553 
Function 18H, Set media type for 
format 554 
Function 19H, Park heads 554 
Function 1AH, Format ESDI drive 555 
Int 14H, ROM BIOS Serial 
communications port driver 111 
Function 00H, Initialize 
communications port 556 
Function 01H, Write character to 
communications port 557 
Function 02H, Read character from 
communications port 558 
Function 03H, Get communications 
port status 558 
Function 04H, Extended initialize 
communications port 558 
Function 05H, Extended 
communications port control 559 
Int 15H, ROM BIOS I/O Subsystem 
Extensions 
Function 00H, Turn on cassette motor 
560 
Function 01H, Turn off cassette motor 
560 
Function 02H, Read cassette 561 
Function 03H, Write cassette 562 
Function OFH, Format ESDI drive 
periodic interrupt 562 
Function 21H 
Subfunction 00H, Read POST error 
log 563 
Subfunction 01H, Write POST error 
log 563 
Function 4FH, Keyboard intercept 564 
Function 80H, Device open 564 
Function 81H, Device close 565 
Function 82H, Process termination 566 
Function 83H, Event wait 566 
Function 84H, Read joystick 567 
Function 85H, SysReq key 568 
Function 86H, Delay 568 
Function 87H, Move extended memory 
block 569 
Function 88H, Get extended memory 
size 570 
Function 89H, Enter protected mode 
570 
Function 90H, Device wait 571 
Function 91H, Device post 572 


Int 15H, continued 
Function COH, Get system 
environment 317, 573 
Function C1H, Get address of extended 
BIOS data area 574 
Function C2H 
Subfunction 00H, Enable/disable 
pointing device 574 
Subfunction 01H, Reset pointing 
device 575 
Subfunction 02H, Set sample rate 
576 
Subfunction 03H, Set resolution 576 
Subfunction 04H, Get pointing 
device type 577 
Subfunction 05H, Initialize pointing 
device interface 577 
Subfunction 06H, Set scaling or get 
status 578 
Subfunction 07H, Set pointing 
device handler address 579 
Function C3H, Set watchdog time-out 
580 
Function C4H, Programmable option 
select 580 
Int 16H, ROM BIOS keyboard driver 322 
Function 00H, Read character from 
keyboard 581 
Function 01H, Get keyboard status 582 
Function 02H, Get keyboard flags 582 
Function 03H, Set repeat rate 583 
Function 04H, Set keyclick 584 
Function 05H, Push character and scan 
code 585 
Function 10H, Read character from 
enhanced keyboard 585 
Function 11H, Get enhanced keyboard 
status 586 
Function 12H, Get enhanced keyboard 
flags 586 
Int 17H, ROM BIOS Parallel port printer 
driver 108-19 
Function 00H, Write character to 
printer 587 
Function 01H, Initialize printer port 
587 
Function 02H, Get printer status 588 
Int 18H, ROM BASIC 588 
Int 19H, ROM BIOS Reboot system 588 
Int 1AH, Real-time (CMOS) Clock Driver 
Function 00H, Get tick count 589 
Function 01H, Set tick count 589 
Function 02H, Get time 590 
Function 03H, Set time 590 
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Function 04H, Get date 591 
Function 05H, Set date 591 
Function 06H, Set alarm 591 
Function 07H, Reset alarm 592 
Function 0AH, Get day count 592 
Function OBH, Set day count 593 
Function 80H, Set sound source 593 


Int 20H, Terminate process 341 
Int 21H, MS-DOS system functions 


function execution in a typical I/O 
request 281-82 

function summary by category 337-40 
(table) 

function summary by number 335-37 
(table) 

Function 00H, Terminate process 342 

Function 01H, Character input with 
echo 70, 148, 343 

Function 02H, Character output 90, 344 

Function 03H, Auxiliary input 110, 
344-45 

Function 04H, Auxiliary output 110, 
345-46 

Function 05H, Printer output 107, 
346-47 

Function 06H, Direct console I/O 70, 
73, 90, 347-48 

Function 07H, Unfiltered character 
input without echo 70, 73, 348—49 

Function 08H, Character input without 
echo 70, 349-50 

Function 09H, Display string 90, 
350-51 

Function OAH, Buffered keyboard 
input 70-71, 351-52 

Function OBH, Check input status 70, 
353 

Function 0CH, Flush input buffer and 
then input 70, 353-54 

Function ODH, Disk reset 354-55 

Function OEH, Select disk 167, 355-56 

Function OFH, Open file 132, 137, 
356-57 

Function 10H, Close file 132, 357-58 

Function 11H, Find first file 358-59 

Function 12H, Find next file 360—61 

Function 13H, Delete file 132, 361—62 

Function 14H, Sequential read 132, 
362-63 

Function 15H, Sequential write 132, 
363-64 

Function 16H, Create file 132, 364-65 
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Int 21H, continued 

Function 17H, Rename file 132, 173, 
366-67 

Function 18H, Reserved 367 

Function 19H, Get current disk 167, 
168, 367 

Function 1AH, Set DTA address 130, 
132, 368 

Function 1BH, Get default drive data 
368-69 

Function 1CH, Get drive data 370 

Function 1DH, Reserved 371 

Function 1EH, Reserved 371 

Function 1FH, Reserved 371 

Function 20H, Reserved 371 

Function 21H, Random read 132, 
372-73 

Function 22H, Random write 132, 
373-75 

Function 23H, Get file size 132, 375-76 

Function 24H, Set relative record 
number 132, 376 

Function 25H, Set interrupt vector 147, 
252, 253, 316, 377-78 

Function 26H, Create new PSP 378-79 

Function 27H, Random block read 132, 
379-80 

Function 28H, Random block write 
132, 381-82 

Function 29H, Parse filename 129, 132, 
382 

Function 2AH, Get date 384-85 

Function 2BH, Set date 385 

Function 2CH, Get time 386 

Function 2DH, Set time 386-87 

Function 2EH, Set verify flag 387-88 

Function 2FH, Get DTA address 
388-89 

Function 30H, Get MS-DOS version 
number 148, 319, 389 

Function 31H, Terminate and stay 
resident 252, 253, 390-91 

Function 32H, Reserved 392 

Function 33H, Get or set break flag, get 
boot drive 392—93 

Function 34H, Reserved 393 

Function 35H, Get interrupt vector 252, 
316, 393-94 

Function 36H, Get drive allocation 
information 394-95 

Function 37H, Reserved 395 

Function 38H, Get or set country 
information 395—98 

Function 39H, Create directory 167, 
398-99 
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Int 21H, continued 
Function 3AH, Delete directory 167, 399 
Function 3BH, Set current directory 167, 
400 
Function 3CH, Create file 140, 401-2 
Function 3DH, Open file 107, 110, 140, 
204, 402-4 
Function 3FH, Close file 140, 204, 404 
Function 3FH, Read file or device 67, 69, 
71, 109, 110, 141, 298, 300, 322, 405-— 
6 
Function 40H, Write file or device 35, 88, 
107, 109, 110, 141, 298, 300, 322, 
406-7 
Function 41H, Delete file 141, 407-8 
Function 42H, Set file pointer 141, 
408-9 
Function 43H, Get or set file attributes 
141, 410-11 
Function 44H, IOCTL C/O control) 69, 
93-94, 111, 204, 205, 411-34 
Subfunction 00H, IOCTL: get device 
information 412-13 
Subfunction 01H, IOCTL: set device 
information 414-15 
Subfunction 02H, IOCTL: read 
control data from character device 
driver 415-16 
Subfunction 03H, IOCTL: write 
control data to character device 
driver 416-17 
Subfunction 04H, IOCTL: read 
control data from block device 
driver 418-19 
Subfunction 05H, IOCTL: write 
control data to block device driver 
419-20 
Subfunction 06H, IOCTL: check 
input status 420-21 
Subfunction 07H, IOCTL: check 
output status 421-22 
Subfunction 08H, IOCTL: check if 
block device is removable 422—23 
Subfunction 09H, IOCTL: check if 
block device is remote 423-24 
Subfunction OAH, IOCTL: check if 
handle is remote 424-25 
Subfunction OBH, IOCTL: change 
sharing retry count 425-26 
Subfunction OCH, IOCTL: generic 
I/O control for character devices 
426-29 


Int 21H, Function 44H, continued 
Subfunction ODH, IOCTL: generic 
I/O control for block devices 
429-32 
Subfunction 0OEH, IOCTL: get logical 
drive map 433 
Subfunction OFH, IOCTL: set logical 
drive map 434 
Function 45H, Duplicate handle 141, 
435 
Function 46H, Redirect handle 141, 299, 
436-37 
Function 47H, Get current directory 
167, 168, 437-38 
Function 48H, Allocate memory block 
196, 202, 323, 438-39 
Function 49H, Release memory block 
196, 323, 439-40 
Function 4AH, Resize memory block 
196, 198, 202, 219, 239, 322, 440—41 
Function 4BH, Execute program 
(EXEC) 202, 299, 441—42 (see also 
EXEC function) 
Function 4CH, Terminate process with 
return code 26, 31, 35, 317, 443-44 
Function 4DH, Get return code 221, 
444-45 
Function 4EH, Find first file 445—46 
Function 4FH, Find next file 446—47 
Function 50H, Reserved 447 
Function 51H, Reserved 447 
Function 52H, Reserved 447 
Function 53H, Reserved 448 
Function 54H, Get verify flag 448 
Function 55H, Reserved 448 
Function 56H, Rename file 141, 173, 
449—50 
Function 57H, Get or set file date and 
time 141, 450-51 
Function 58H, Get or set allocation 
strategy 452-53 
Function 59H, Get extended error 
information 130, 145, 148, 453-56 
Function 5AH, Create temporary file 
141, 457-58 
Function 5BH, Create new file 141, 
458-59 
Function 5CH, Lock or unlock file 
region 141, 460-61 
Function 5DH, Reserved 461 
Function 5EH, Machine name and 
printer setup 
Subfunction 00H, Get machine 
name 461-62 


Int 21H, Function 5EH, continued 
Subfunction 02H, Set printer setup 
string 462-63 
Subfunction 03H, Get printer setup 
string 463—64 
Function 5FH, Device redirection 
Subfunction 02H, Get redirection list 
entry 464-65 
Subfunction 03H, Redirect device 
466-67 
Subfunction 04H, Cancel device 
redirection 467—68 
Function 60H, Reserved 468 
Function 61H, Reserved 468 
Function 62H, Get PSP address 468-69 
Function 63H, Get DBCS lead byte 
table 469-70 
Function 64H, Reserved 470 
Function 65H, Get extended country 
information 470-74 
Function 66H, Get or set code page 
474-75 
Function 67H, Set handle count 141, 
475-76 
Function 68H, Commit file 141, 476-77 
Function 69H, Reserved 477 
Function 6AH, Reserved 477 
Function 6BH, Reserved 477 
Function 6CH, Extended open file 141, 
478-80 
Int 22H, Terminate handler address 480 
Int 23H, Ctrl-C handler address 317, 
480-81 
Int 24H, Critical-error handler address 
147, 317, 481-82 
Int 25H, Absolute disk read 482-84 
Int 26H, Absolute disk write 319, 484-85 
Int 27H, Terminate and stay resident 
486-87 
Int 28H, Reserved 487 
Int 29H, Reserved 487 
Int 2AH, Reserved 487 
Int 2BH, Reserved 487 
Int 2CH, Reserved 487 
Int 2DH, Reserved 488 
Int 2EH, Reserved 488 
Int 2FH, Multiplex interrupt 488 
Function 01H, Print spooler 488-89 
Function 02H, ASSIGN 489 
Function 10H, SHARE 490 
Function B7H, APPEND 490-91 
Int 33H, Microsoft Mouse driver 593 
Function 00H, Reset mouse and get 
status 80, 594 
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Int 33H, continued 


Function 01H, Show mouse pointer 80, 
594 

Function 02H, Hide mouse pointer 80, 
595 

Function 03H, Get mouse position and 
button status 80, 595 

Function 04H, Set mouse pointer 
position 80, 596 

Function 05H, Get button press . 
information 80, 596 

Function 06H, Get button release 
information 80, 597 

Function 07H, Set horizontal limits for 
pointer 80, 597 

Function 08H, Set vertical limits for 
pointer 80, 598 

Function 09H, Set graphics pointer 
shape 80, 598 

Function OAH, Set text pointer type 80, 
599 

Function OBH, Read mouse motion 
counters 80, 599 

Function OCH, Set user-defined mouse 
event handler 80, 600 

Function ODH, Turn on light pen 
emulation 80, 601 © 

Function 0EH, Turn off light pen 
emulation 80, 601 

Function OFH, Set mickeys to pixels 
ratio 80, 601 

Function 10H, Set mouse pointer 
exclusion area 80, 602 

Function 13H, Set double speed 
threshold 81, 602 

Function 14H, Swap user-defined 
mouse event handlers 81, 603 

Function 15H, Get mouse save state 
buffer size 81, 603 

Function 16H, Save mouse driver state 
81, 604 

Function 17H, Restore mouse driver 
state 81, 604 

Function 18H, Set alternate mouse 
event handler 81, 604 

Function 19H, Get address of alternate 
mouse event handler 81, 606 

Function 1AH, Set mouse sensitivity 81, 
606 

Function 1BH, Get mouse sensitivity 
81, 607 

Function 1CH, Set mouse interrupt rate 
81, 607 
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Int 33H, continued 


Function 1DH, Select pointer page 81, 
608 

Function 1EH, Get pointer page 81, 608 

Function 1FH, Disable mouse driver 81 
608 

Function 20H, Enable mouse driver 81, 
609 : 

Function 21H, Reset mouse driver 81, 
609 

Function 22H, Set language for mouse 
driver messages 81, 610 

Function 23H, Get language number 
81, 610 

Function 24H, Get mouse information 
81, 611 
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Int 67H, Expanded Memory Manager 


functions 204, 205, 207 
Function 40H, Get status 616 
Function 41H, Get page frame address 
616 
Function 42H, Get number of pages 
617 
Function 43H, Allocate handle and 
pages 617 
Function 44H, Map expanded memory 
page 618 
Function 45H, Release handle and 
expanded memory 619 
Function 46H, Get version 619 
Function 47H, Save page map 620 
Function 48H, Restore page map 620 
Function 49H, Reserved 621 
Function 4AH, Reserved 621 
Function 4BH, Get handle count 621 
Function 4CH, Get handle pages 622 
Function 4DH, Get pages for all 
handles 623 
Function 4EH 
Subfunction 00H, Save page map 
623 
Subfunction 01H, Restore page map 
624 
Subfunction 02H, Save and restore 
page map 624 
Subfunction 03H, Get size of page 
map information 625 
Function 4FH 
Subfunction 00H, Save partial page 
map 625 
Subfunction 01H, Restore partial 
page map 626 
Subfunction 02H, Get size of partial 
page map information 626 


Int 67H, continued 
Function 50H 
Subfunction 00H, Map multiple 
pages by number 627 
Subfunction 01H, Map multiple 
pages by address 627 
Function 51H, Reallocate pages for 
handle 628 
Function 52H 
Subfunction 00H, Get handle 
attribute 629 
Subfunction 01H, Set handle 
attribute 629 
Subfunction 02H, Get attribute 
capability 630 
Function 53H 
Subfunction 00H, Get handle name 
630 
Subfunction 01H, Set handle name 
631 
Function 54H 
Subfunction 00H, Get all handle 
names 631 
Subfunction 01H, Search for handle 
name 632 
Subfunction 02H, Get total handles 
632 | 
Function 55H 
Subfunctions 00H and 01H, Map 
pages and jump 633 
Function 56H 
Subfunctions 00H and 01H, Map 
pages and call 633 
Subfunction 02H, Get stack space for 
map page and call 634 
Function 57H 
Subfunction 00H, Move memory 
region 635 
Subfunction 01H, Exchange memory 
regions 635 
Function 58H 
Subfunction 00H, Get addresses of 
mappable pages 636 
Subfunction 01H, Get number of 
mappable pages 637 
Function 59H 
Subfunction 00H, Get hardware 
configuration 637 
Subfunction 01H, Get number of raw 
pages 638 
Function 5AH 
Subfunction 00H, Allocate handle 
and standard pages 638 
Subfunction 01H, Allocate handle 
and raw pages 639 


Int 67H, continued 
Function 5BH 
Subfunction 00H, Get alternate map 
registers 639 
Subfunction 01H, Set alternate map 
registers 640 
Subfunction 02H, Get size of 
alternate map register save area 
641 
Subfunction 03H, Allocate alternate 
map register set 641 
Subfunction 04H, Deallocate 
alternate map register set 642 
Subfunction 05H, Allocate DMA 
register set 
Subfunction 06H, Enable DMA on 
alternate map register set 643 
Subfunction 07H, Disable DMA on 
alternate map register set 643 
Subfunction 08H, Deallocate DMA 
register set 644 
Function 5CH, Prepare expanded 
memory manager for warm boot 
644 
Function 5DH 
Subfunction 00H, Enable EMM 
operating system functions 645 
Subfunction 01H, Disable EMM 
operating system functions 645 
Subfunction 02H, Release access key 
646 
Intel 80x86 microprocessor family 4, 8, 
38, 64, 203 
interrupts and 246-51 
Intel 8259A Programmable Interrupt 
Controller 112, 320 
internal hardware interrupts 246 
internal (intrinsic) commands 14 
interrupt(s) 13, 244-45. See also Int 10H 
through Int 67H 
external hardware 247 
internal hardware 246 
servicing 250-51 
software 247—49 
types 244 
interrupt handlers 16 
example (ZERODIV.ASM) 254-58 
MS-DOS and 252-53 
servicing 250, 251 
tasks 245 
typical 251 
interrupt (intr) routine, device-driver 
266-67, 293. See also command 
code routines 
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interrupt vector 17, 244 
get 393-94 
set 377-78 
interrupt vector table 250 
IOCTL (I/O control). See Int 21H, 
Function 44H 
IO.SYS file 16, 17 
memory location of 18 
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Japanese character set 6 
joystick, read 567 


K 


kernel. See DOS kernel 
keyboard 
get enhanced flags 586-87 
get enhanced status 586 
get flags 582 
get status 582 
input with/without echo 70 
intercept 564 
key repeat rate and delay 583-84 
push character and scan code in buffer 
585 
read character from 581 
read character from enhanced 585 
set keyclick 584 
keyboard input 65-72 
buffered 351-52 
Ctrl-C and Ctrl-Break handlers 72-80, 
317 
with handles 66, 67-69 
read character from keyboard 581 
with ROM BIOS functions 71-72 
with traditional calls 69-71 
Keyboard input with echo 70 
Keyboard input without echo 70 
Keyboard intercept 564 
Korean character set 6 


L 


.LIB files 44, 45, 58. See also Library 
Manager (LIB) 

Library Manager (LIB) 44, 58-60 
operations prefix characters 58 
table-of-contents listing for SLIBC.LIB 

59 

light pen 
get position 503 
turn off emulation 601 
turn on emulation 601 
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line printer (PRN) 12, 106, 298 

LINK. See Object Linker (LINK) 

Load ROM 8-by-8 font 519 

Load ROM 8-by-14 font 518-19 

Load ROM 8-by-16 font 520-21 

Load user font 518 

Lock or unlock file region 460-61 

Lotus/Intel/Microsoft Expanded Memory 
(LIM EMS). See Expanded Memory 
Specification CEMS) 

LPT1, LPT2, LPT3 devices 106, 298 

.LST files 45 


M 


machine name, get 461-62 
Macro Assembler (MASM) 44, 45—47 
command line mode 46 
interactive mode 46 
levels 
modules 37 
procedures 41—42 
segments 38-41 
tutorials 63 
version 5.1 switches 47 
make files 61 
MAKE utility 60—61 
switches for 61 
Map expanded memory page (EMS) 618 
MAP files 45 
Map multiple pages by address (EMS) 
627-28 


Map multiple pages by number (EMS) 
627 


Map pages and call (EMS) 633-34 
MASM. See Macro Assembler (MASM) 
master boot record 192 
Media Check (function 01H) 270-71 
memory 
allocation 
dynamic, of additional 199-201 
shrinking 197-99 
conventional 196 
moving blocks of data between 
extended memory and 2173-15 
expanded (see Expanded Memory 
Specification (EMS)) 
image of .COM file 26 
image of .EXE file 37 
location of disk bootstrap program in 
17 
location of IO.SYS in 78 
location of ROM bootstrap routine in 


16 


memory, continued 
location of SYSINIT, DOS kernel, 
MSDOS.SYS in 19 
making available, for EXEC function 
218-19 
map after startup 20 
RAM 196 
memory areas, 196. See also arena entries; 
arena headers; transient program 
area (TPA) 
memory block 
allocate 438-39 
get/set allocation strategy 452-53 
move extended 569-60 
release 439-40 
resize 440—41 
memory interlace 203 
memory management 195-215 
arena headers 201-2 
expanded memory 203-11 
using 207-11 
extended memory 212-15 
Int 21H functions summary 339 
MS-DOS applications compatibility 
and 316 
using memory-allocation functions 
197-202 
memory-mapped input/output 86, 
96-103 
graphics mode 101-3 
text mode 96-101 
memory models 39 
segments, groups, classes for 40 
memory segment 321-22 
memory size 
get conventional 536 
get extended 570 
mickeys, set to pixel ratio 601 
Microsoft Mouse driver 593-611 
miscellaneous system functions, Int 21H 
functions summary 340 
MKDIR (MD) command 167 
Monochrome/Printer Display Adapter 
(MDA) 86, 97, 98 
example dump, regen buffer 98 
MOUDEMO.C program 82-83 
mouse. See also pointing device 
disable driver 608-9 
driver 593 
enable driver 609 
get address of alternate event handler 
606 
get button press information 596 
get button release information 597 


mouse, continued 
get information 611 
get language number 610 
get mouse save state buffer size 603-4 
get position and button status 595 
get sensitivity 607 
hide pointer 595 
input 80-83 
read motion counters 599-600 
reset and get status 594 
reset driver 609 
save driver state 604 
set alternate event handler 604-5 
set double speed threshold 602 
set graphics pointer shape 598 
set interrupt rate 607 
set language for driver messages 610 
set pointer exclusion area 602 
set pointer horizontal limits 597-98 
set pointer page 608 
set pointer position 596 
set pointer vertical limits 598 
set sensitivity 606 
set text pointer type 599 
set user-defined event handler 
600-601 
show pointer 594-95 
summary of function calls 494-99 
swap user-defined event handlers 603 
Move extended memory block 569-70 
Move memory region (EMS) 635 
MS-DOS. See also Operating System/2 
(OS/2) 
genealogy 3-9 
interrupt handlers and 252-53 
loading 16-20 
programming tools (see programming 
tools) 
structure 12-16 
MS-DOS application programs, porting to 
OS/2 318-31 
conversion 326-30 
encapsulation 323, 324-25 
MS-DOS function calls and OS/2 
counterparts 328-29 
optimization 330-31 
rationalization 322—23 
ROM BIOS functions and OS/2 
equivalents used in MS-DOS 
applications 330 
segmentation 321-22 
MS-DOS application programs, structure 
of 21-42 
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MS-DOS application programs, continued 


assembly-language programs 27-30, 
37-42 
.COM programs introduced 25-30 
creation of 62-63 
EXE programs introduced 30-36 
program procedures 41—42 
program segment prefix 23-25 
MS-DOS application programs, writing 
compatible 314, 315-17 
check host capabilities 316 
exception handling 317 
input and output 316 
memory management 316 
process management 317 
program structure 315 
MS-DOS error codes 145-51 
MS-DOS functions 334 
conversion of, to OS/2 function calls 
326-27 
display functions 88-94 
binary output mode 93-94 
screen control 91-93 
EXEC (see EXEC function) 
file control block (FCB) 129-39 
handle 139-44 
memory management/allocation 196, 
197-202 
OS/2 equivalents to 328-29 
printer output 107-9 
reference (see Section IT) 
serial port 109-12 
typical in-line code for call to 324 
MSDOS.SYS file 13, 16 
memory location of 19 
MS-DOS versions 
1.0 4-5, 138 
1.255 
2.00 5-6, 174 
error codes 145 
volume-label search under 175 
2.11, 2.25 6 
3.0 6-7, 138, 174 
error codes 145—46 
volume-label search under 776 
3:1) 3.23 3.5;4.0 7 
get number 389-90 
support for select command code 
routines by 267—68 (table) 
Multi-Color Graphics Array (MCGA) 86, 
102 
Multiplex interrupt 488 
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NAME statement 27, 33 
NEAR attribute 27 
vs FAR 29 
NEAR RETURN 27 
network functions, Int 21H functions 
summary 339 
Nondestructive Read (function 05H) 274 
non-disk-related errors 147, 148 (table) 


O 


Object Linker (LINK) 37, 44, 50-55 
map produced by, of HELLO.EXE 
program 5] 
switches accepted by 53-55 
object modules 37 
libraries (see Library Manager (LIB)) 
linking .COM files from 27, 37. See also 
Object Linker (LINK) 
.OBJ files 45 
Open file 356-57, 402-4 
Operating System/2 (OS/2) 7 
code optimization 330-31 
compatibility issues 318-20 
function calls equivalent to MS-DOS 
function calls 328-29 
function calls equivalent to ROM BIOS 
function calls 330 
porting MS-DOS applications to OS/2 
320-31 
ORG instruction 29 
output. See character input/output; 
printer output; serial port 
output status, check 421-22 
Output Status (command-code function 
OAH) 276 
Output Until Busy (function 10H) 278-79 
overlays, loading with EXEC 240, 241-42 
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PAGE command 27, 33 
page frame 203 
palette 
enable/disable default 526-27 
get border and 514 
get register 513 
set 508-9 
set border and 512-13 
set register 511-12 
parallel ports 106 


parameter block, requesting EXEC 
function 220-21 
parent programs 218 
Park heads 554-55 
Parse filename 382-84 
partitions, fixed-disk 192-94 
Paterson, Tim 4 
path 166 
PC-DOS 
version 1.0 4 
version 1.15 
version 2.0 5-6 
version 3.0 193-94 
piping parameters 24 
pixel 101 
formula to calculate bit position for 
102-3 
read graphics 510 
set mickeys to pixel ratio 601-2 
write graphics 509 
pointing device 
enable/disable 574-75 
get device type 577 
get scaling or get status 578-79 
initialize interface 577-78 
input 80-83 
reset 575 
set handler address 579-80 
set resolution 576-77 
set sample rate 576 
POP instruction 35 
portability. See compatibility and 
portability 
POST (power-on self-test) 
read error log 563 
write error log 563-64 
Prepare expanded memory manager for 
warm boot (EMS) 644-45 
Presentation Manager, OS/2 318 
printer 106, 107-9. See also line printer 
(PRN); standard printer (stdprn) 
get setup strings 463-64 
get status 588 
initialize port 587 
write character to 587 
printer output 106, 107-9, 346—47. See 
also TALK.ASM program 
printer setup string 
get 463-64 
set 462-63 
printscreen, select alternate 526 
Print spooler 488-89 
PRN device 12, 106, 298-99 


PROC command 29, 35, 41 
procedure, declaring beginning/end of 


process management 
for compatibility in MS-DOS 
applications 317 
Int 21H functions summary 339 
terminate process 566 
Process termination 566 
Programmable Interrupt Controller (PIC) 
247 
Programmable option select 580-81 
programming tools 43-64 
C Optimizing compiler 48-50 
CREF utility 56-58 
example using 62—63 
EXE2BIN utility 55-56 
file types 45 
Library Manager 58—60 
MAKE utility 60-61 
MASM 45-47 (see also Macro 
Assembler (MASM)) 
Object Linker 50-55 (see also Object 
Linker (LINK)) 
resources and references 63—64 
program modules, assembly-language 37 
program procedures 41—42 
program segment prefix (PSP) 15, 23-25 
create new 378-79 
get address 468-69 
structure of 23 
program segments, assembly-language 
38-41 
protected mode, enter 570-71 
PROTO.ASM program 301-2 
PROTO.C program 303 
P-system operating system 5 
Push character and scan code 585 
PUSH instruction 35 
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Random block read 379-80 

Random block write 381-82 

Random read 372-73 

Random write 373-75 

rationalizing code 322—23 

raw mode 69 

Read (function 04H) 273 

Read cassette 561 | 

Read character and attribute at cursor 506 

Read character from communications 
port 558 


Index 665 


Read character from enhanced keyboard 
585 
Read character from keyboard 581 
Read control data from block-device 
driver 418-19 
Read control data from character device 
driver 415-16 
Read file or device 405-6 
Read graphics pixel 510 
Read joystick 567 
Read mouse motion counters 599-600 
Read POST error log 563 
Read sector 538-39 
Read sector buffer 548 
Read sector long 545—46 
Reallocate pages for handle (EMS) 628 
Reboot system 588-89 
Recalibrate drive 550 
record(s) 
set relative number 376-77 
using FCB functions 129-39 
using handle functions 139-44 
record operations, Int 21H functions 
summary 338-39 
Redirect device 466-67 
Redirect handle 436-37 
redirection, input/output 24, 67, 298-99 
cancel 467-68 
redirection list entry, get 464—65 
.REF files 45, 56 
refresh buffer 86 
regen buffer 86 
example dump of MDA adapter 98 
formula to determine offset 102 
memory diagram showing location of 


Release access key (EMS) 646 
Release handle and expanded memory 
(EMS) 619 
Release memory block 439-40 
Removable Media (function 0FH) 278 
REN(AME) command 14 
Rename file 366-67, 449-50 
request header format 265 
command codes for (see command 
code routines, device-driver) 
reserved area, disk 182 
reserved functions 
EMS 621 
Int 21H functions summary 340 
Reset alarm 592 
Reset disk system 536-37 
Reset fixed disk system 548 
Reset mouse and get status 594 
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Reset mouse driver 609 
Reset pointing device 575 
resident device drivers 12 
Resize memory block 440-41 
RESTORE command 15 
Restore mouse driver state 604 
Restore page map (EMS) 620-21, 624 
Restore partial page map (EMS) 626 
RET instruction 41 
retrace interval 100 
return code 
get 444 
terminate process with 443-44 
RMDIR (RD) command 167 
ROM 8-by-8 font 
load 519 
set Int 43H for 523 
ROM 8-by-14 font 
load 518-19 
set Int 43H for 522-23 
ROM 8-by-16 font 
load 520-21 
set Int 43H for 523-24 
ROM BASIC 588 
ROM BIOS 
display functions 94-96, 330 
interrupts of special importance to 247, 
248—49 
keyboard functions 67 
input with 71-72 
ROM BIOS compatibility 314-16, 317-18 
avoid unstable hardware 318 
check host capabilities 317-18 
functions of, and OS/2 equivalents 330 
ROM BIOS function calls. See also 
Section II 
summary 494-99 
ROM bootstrap routine 16 
root directory 166, 184-86, 187 
partial hex dump 186 
RS-232 serial-interface standard 106 
RS-422 serial-interface standard 106 
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Save and restore page map (EMS) 624-25 

Save mouse driver state 604 

Save or restore video state 534-35 

Save page map (EMS) 620, 623 

Save partial page map (EMS) 625-26 

scan lines, set 526 

screen control with MS-DOS functions 
91-93 

screen refresh, enable/disable 529 


Search for handle name (EMS) 632 
Seattle Computer Products 4 
Seek 547 
SEGMENT command 29, 33, 38 
segment register 321 
Select alternate printscreen 526 
Select disk 355-56 
selector 321 
Select pointer page 608 
Sequential read 362-63 
Sequential write 363—64 
serial port 106, 109-12. See also 
TALK.ASM program 
extended initialize port 558-59 
extended port control 559-60 
get status 558 
initialize 556-57 
read character from 558 
write character to 557 
Set alarm 591-92 
Set alternate map registers (EMS) 640 
Set alternate mouse event handler 604—5 
Set block of color registers 515 
Set block specifier 520 
Set border color 512 
Set color page state 515-16 
Set color register 514-15 
Set current directory 400 
Set cursor position 501-2 
Set cursor type 501 
Set date 385, 591 
Set day count 593 
Set device information 414-15 
Set disk type 553 
Set display page 503-4 
Set double speed threshold 602 
Set DTA address 368 
Set file pointer 408-9 
Set graphics pointer shape 598 
Set gray-scale values 517 
Set handle attribute (EMS) 629 
Set handle count 475-76 
Set handle name (EMS) 631 
Set horizontal limits for pointer 597-98 
Set Int IFH font pointer 521 
Set Int 43H for ROM 8-by-8 font 523 
Set Int 43H for ROM 8-by-14 font 522-23 
Set Int 43H for ROM 8-by-16 font 523-24 
Set Int 43H for user’s font 522 
Set interrupt vector 377-78 
Set keyclick 584 
Set language for mouse driver messages 
610 
Set Logical Device (function 18H) 280-81 


Set logical drive map 434 
Set media type for format 554 
Set mickeys to pixels ratio 601 
Set mouse interrupt rate 607 
Set mouse pointer exclusion area 602 
Set mouse pointer position 596 
Set mouse sensitivity 606 
Set palette and border 512-13 
Set palette, background, or border 508-9 
Set palette register 511-12 
Set pointing device handler address 
379-80 
Set printer setup string 462—63 
Set relative record number 376-77 
Set repeat rate 583-84 
Set resolution 576-77 
Set sample rate 576 
Set scaling or get status 578-79 
Set scan lines 526 
Set sound source 593 
Set text pointer type 599 
Set tick count 589-90 
Set time 386-87, 590 
Set user-defined mouse event handler 
600-601 
Set verify flag 387-88 
Set vertical limits for pointer 598 
Set video mode 500-501 
Set watchdog time-out 580 
SHARE 490 
shell. See COMMAND.COM file; 
command processor (shell) 
SHELL.ASM program 229-38 
SHELL.C program 225-29 
Show mouse pointer 594—95 
SLIBC.LIB, table-of-contents listing for 
59 
Softech company 5 
software interrupts, 247—49 
sound source, set 593 
STACK attribute 31 
stack pointer (SP) register 25—26, 31, 35 
stack segment 38 
stack segment (SS) register 31, 35 
standard auxiliary device (stdaux) 20, 
323 
default device 298 
handle 66 
standard error device (stderr) 20 
default device 298 
handle 66 
standard input device (stdin) 20 
default device 298 
handle 66, 67 
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standard list device 20, 323 
standard output device (stdout) 20 
default device 298 
handle 66 
standard printer (stdprn) 
default device 298 
handle 66 
strategy (straf) routine, device-driver 
265, 293 
string(s) 
display 350-51 
Swap user-defined mouse event handlers 
603 
Switch active display 528-29 
switches 
C Optimizing compiler 49—50 
Library Manager 60 
Macro Assembler 47 
Make utility 67 
Object Linker 53-55 
SYSINIT module 17, 18, 20 
installing device drivers 293 
memory location of 79 
SysReq key 568 
system file table 140—41 


T 


TALK.ASM program 113-26 
teletype mode 
write character in 510-11 
write string in 529-30 
terminal-emulator program. See 
TALK.ASM program 
Terminate and stay resident 390-91, 
486-87 
Terminate handler address 480 
Terminate process 341, 342 
Terminate process with return code 
443-44 
text-mode memory-mapped 
programming 96-101 
threads 331 
time and date 
day count 592, 593 
get date 384-85, 591 
get time 386, 590 
set date 385, 591 
set time 386-87, 590 
TITLE command 27, 33 
Toggle blink/intensity bit 513 
transient program 15, 22. See also .COM 
program file(s); EXE (executable) 
program file(s) 
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transient program area (TPA) 15, 196. See 
also arena entries; arena headers 

TREE command 174 

TRYBREAK.C program 78—79 

Turn off cassette motor 560-61 

Turn on cassette motor 560 

Turn off light pen emulation 601 

Turn on light pen emulation 601 


U 


Unfiltered character input without echo 
348-49 
UNIX/XENIX operating system 66, 128, 
139 
user font 
load 518 
set Int 1FH pointer 521 
set Int 43H for 522 


Vv 


verify flag, get 448 
Verify sector 540 
video display 85-103 
adapters 86-87 
enable/disable 527 
get functionality/state information 
531-34 
get or set combination code 530-31 
memory-mapped techniques 96-103 
graphics mode 101-3 
text mode 96-101 
MS-DOS display functions 88-94 
binary output mode 93-94 
screen control with 91-93 
ROM BIOS display functions 94-96 
save or restore video state 534-35 
support considerations 88 
switch active display 528-29 
Video Graphics Array (VGA) 86, 97, 98, 
102 
video mode 
get 511 
set 500-501 
VOL command 174 
volume labels 174-76 
search, using extended file control 
block 175 
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watchdog time-out, set 580 
window 
initialize or scroll down 505-6 
initialize or scroll up 505 
Windows 7, 318 
Write (function 08H) 275 
Write cassette 562 
Write character and attribute at cursor 
506-7 
Write character at cursor 507-8 
Write character in teletype mode 510-11 
Write character to communications port 
557 
Write character to printer 587 
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